+Sun Feb 11 22:16:34 2001 Owen Taylor <otaylor@redhat.com>
+
+ * */Makefile.am: Use the new snazzy mother-of-all-gtk-doc-makefiles.
+
+ * gdk/tmpl/* gdk-pixbuf/tmpl/*: Recover a bunch of docs that were
+ lost at one point.
+
2001-02-08 Havoc Pennington <hp@pobox.com>
* gtk/windows.sgml: windows (file is blank)
# The top-level SGML file.
DOC_MAIN_SGML_FILE=gdk-pixbuf.sgml
-# The directory containing the source code (if it contains documentation).
-DOC_SOURCE_DIR=$(GDK_PIXBUF_DIR)/gdk-pixbuf
-SECOND_DOC_SOURCE_DIR=$(top_srcdir)/contrib/gdk-pixbuf-xlib
+# The directory containing the source code. Relative to $(srcdir)
+DOC_SOURCE_DIR=../../../gdk-pixbuf
+
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=
+# Used for dependencies
+HFILE_GLOB=$(top_srcdir)/gdk-pixbuf/*.h $(top_srcdir)/contrib/gdk-pixbuf-xlib/*.h
+CFILE_GLOB=$(top_srcdir)/gdk-pixbuf/*.c $(top_srcdir)/contrib/gdk-pixbuf-xlib/*.c
+
# Header files to ignore when scanning
-IGNORE_HFILES=pixops.h pixops-internal.h gdk-pixbuf-xlib-private.h gdk-pixbuf-i18n.h gdk-pixbuf-private.h
+IGNORE_HFILES= \
+ pixops \
+ gdk-pixbuf-xlib-private.h \
+ gdk-pixbuf-i18n.h \
+ gdk-pixbuf-private.h
# Extra files to add when scanning
-EXTRA_HFILES= \
- $(top_srcdir)/gtk/gdk-pixbuf-loader.h
-
-# CFLAGS and LDFLAGS for compiling scan program
-CFLAGS=
-LDFLAGS=
-
-tmpl_sources = \
- tmpl/animation.sgml \
- tmpl/creating.sgml \
- tmpl/file-loading.sgml \
- tmpl/gdk-pixbuf-loader.sgml \
- tmpl/gdk-pixbuf-unused.sgml \
- tmpl/gdk-pixbuf.sgml \
- tmpl/initialization_versions.sgml \
- tmpl/module_interface.sgml \
- tmpl/refcounting.sgml \
- tmpl/scaling.sgml \
- tmpl/util.sgml \
- tmpl/gdk-pixbuf-xlib-from-drawables.sgml \
- tmpl/gdk-pixbuf-xlib-init.sgml \
- tmpl/gdk-pixbuf-xlib-rendering.sgml \
- tmpl/gdk-pixbuf-xlib-rgb.sgml
+EXTRA_HFILES=
+
+# Images to copy into HTML directory
+HTML_IMAGES =
# Extra SGML files that are included by DOC_MAIN_SGML_FILE
content_files = \
gdk-pixbuf.sgml \
porting-from-imlib.sgml
+# Other files to distribute
+extra_files =
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed
+# if $(DOC_MODULE).types is non-empty.
+GTKDOC_CFLAGS = @STRIP_BEGIN@ \
+ @CFLAGS@ \
+ -I$(top_srcdir) \
+ @GLIB_CFLAGS@ \
+ @more_cflags@ \
+@STRIP_END@
+
+GTKDOC_LIBS = @STRIP_BEGIN@ \
+ $(top_builddir)/gdk-pixbuf/libgdk_pixbuf-1.3.la \
+ @more_ldflags@ \
+ @more_libs@ \
+ @GLIB_LIBS@ \
+ -lm \
+@STRIP_END@
+
+GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
+GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
+
+
####################################
# Everything below here is generic #
####################################
TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
EXTRA_DIST = \
- $(DOC_MODULE).types \
- $(DOC_MAIN_SGML_FILE) \
$(content_files) \
+ $(extra_files) \
+ $(HTML_IMAGES) \
+ $(DOC_MAIN_SGML_FILE) \
+ $(DOC_MODULE).types \
$(DOC_MODULE)-sections.txt \
$(DOC_MODULE)-overrides.txt
+DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp
+
if ENABLE_GTK_DOC
-all-local: html/index.html
+all-local: html-build.stamp
+
+SCANOBJ_FILES = \
+ $(DOC_MODULE).args \
+ $(DOC_MODULE).hierarchy \
+ $(DOC_MODULE).signal
+
+scan-build.stamp: $(HFILE_GLOB)
+ @echo '*** Scanning header files ***'
+ cd $(srcdir) && ( \
+ if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \
+ else \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
+ fi )
+ cd $(srcdir) && \
+ gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
+ touch scan-build.stamp
+
+check_scan:
+ $(MAKE) scan-build.stamp
-$(DOC_MODULE)-decl.txt:
- $(MAKE) scan
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan
-$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
- $(MAKE) templates
+tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
+ @echo '*** Rebuilding template files ***'
+ cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+ touch tmpl-build.stamp
-sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt
- $(MAKE) sgml
+check_templates:
+ $(MAKE) tmpl-build.stamp
-html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE) $(content_files)
- $(MAKE) html
-endif
+tmpl.stamp: check_templates
-scan:
- -(cd $(srcdir) \
- && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --source-dir=$(SECOND_DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(EXTRA_HFILES))
+sgml-build.stamp: tmpl.stamp $(CFILE_GLOB)
+ @echo '*** Building SGML ***'
+ cd $(srcdir) && \
+ gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
+ touch sgml-build.stamp
-templates:
- cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+check_sgml:
+ $(MAKE) sgml-build.stamp
-sgml:
- cd $(srcdir) \
- && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --source-dir=$(SECOND_DOC_SOURCE_DIR)
+sgml.stamp: check_sgml
-html:
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE)
+ @echo '*** Building HTML ***'
test -d $(srcdir)/html || mkdir $(srcdir)/html
- -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
@echo '-- Fixing Crossreferences'
cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
+ touch html-build.stamp
+endif
clean-local:
- rm -f *~ *.bak *.signals *-unused.txt
+ rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp
maintainer-clean-local: clean
cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
dist-check-gtkdoc:
else
dist-check-gtkdoc:
- @echo "*** gtk-doc must be installed and enabled in order to make dist
+ @echo "*** gtk-doc must be installed and enabled in order to make dist"
@false
endif
-dist-hook: dist-check-gtkdoc
- mkdir $(distdir)/html
- mkdir $(distdir)/sgml
+dist-hook: dist-check-gtkdoc dist-hook-local
mkdir $(distdir)/tmpl
- -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(srcdir)/html/index.sgml $(distdir)/html
+ mkdir $(distdir)/sgml
+ mkdir $(distdir)/html
-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
+ -cp $(srcdir)/html/index.sgml $(distdir)/html
+ -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
+ for i in $(HTML_IMAGES) ; do \
+ cp $(srcdir)/$$i $(distdir)/html ; \
+ done
+
+.PHONY : check_sgml check_templates check_scan dist-hook-local
-.PHONY : html sgml templates scan
<!-- ##### SECTION Title ##### -->
-animation
+Animations
<!-- ##### SECTION Short_Description ##### -->
-
+Animations as multi-frame structures.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ The &gdk-pixbuf; library provides a simple mechanism to load and
+ represent animations, primarily animated GIF files. Animations
+ are represented as lists of #GdkPixbufFrame structures. Each
+ frame structure contains a #GdkPixbuf structure and information
+ about the frame's overlay mode and duration.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ #GdkPixbufLoader
+ </para>
<!-- ##### ENUM GdkPixbufFrameAction ##### -->
-<para>
-
-</para>
-
-@GDK_PIXBUF_FRAME_RETAIN:
-@GDK_PIXBUF_FRAME_DISPOSE:
-@GDK_PIXBUF_FRAME_REVERT:
+ <para>
+ Each animation frame can have several things happen to it when the
+ next frame is displayed. The #GdkPixbufFrameAction determines
+ this. These are essentially the overlay modes supported by GIF
+ animations.
+ </para>
+
+@GDK_PIXBUF_FRAME_RETAIN: The previous image should remain displayed,
+and will potentially be occluded by the new frame.
+@GDK_PIXBUF_FRAME_DISPOSE: The animation will be reverted to the state
+before the frame was shown.
+@GDK_PIXBUF_FRAME_REVERT: The animation will be reverted to the first
+frame.
<!-- ##### STRUCT GdkPixbufFrame ##### -->
-<para>
-
-</para>
+ <para>
+ This structure describes a frame in a #GdkPixbufAnimation. Each
+ frame consists of a #GdkPixbuf, an offset of the frame within the
+ animation's bounding box, a duration, and an overlay mode or
+ action.
+ </para>
<!-- ##### STRUCT GdkPixbufAnimation ##### -->
-<para>
-
-</para>
+ <para>
+ This structure describes an animation, which is represented as a
+ list of #GdkPixbufFrame structures.
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_animation_new_from_file ##### -->
</para>
@frame:
-@Returns:
+@Returns: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
<!-- ##### SECTION Title ##### -->
-creating
+Image Data in Memory
<!-- ##### SECTION Short_Description ##### -->
-
+Creating a pixbuf from image data that is already in memory.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ The most basic way to create a pixbuf is to wrap an existing pixel
+ buffer with a #GdkPixbuf structure. You can use the
+ gdk_pixbuf_new_from_data() function to do this You need to specify
+ the destroy notification function that will be called when the
+ data buffer needs to be freed; this will happen when a #GdkPixbuf
+ is finalized by the reference counting functions If you have a
+ chunk of static data compiled into your application, you can pass
+ in #NULL as the destroy notification function so that the data
+ will not be freed.
+ </para>
+
+ <para>
+ The gdk_pixbuf_new() function can be used as a convenience to
+ create a pixbuf with an empty buffer. This is equivalent to
+ allocating a data buffer using malloc() and then wrapping it with
+ gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will
+ compute an optimal rowstride so that rendering can be performed
+ with an efficient algorithm.
+ </para>
+
+ <para>
+ As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
+ function to create a pixbuf from inline XPM image data.
+ </para>
+
+ <para>
+ You can also copy an existing pixbuf with the gdk_pixbuf_copy()
+ function. This is not the same as just doing a gdk_pixbuf_ref()
+ on the old pixbuf; the copy function will actually duplicate the
+ pixel data in memory and create a new #GdkPixbuf structure for it.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ gdk_pixbuf_finalize().
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_new ##### -->
<para>
</para>
@pixbuf:
-@Returns:
-<!-- # Unused Parameters # -->
-@src:
+@Returns: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
<!-- ##### SECTION Title ##### -->
-file-loading
+File Loading
<!-- ##### SECTION Short_Description ##### -->
-
+Loading a pixbuf from a file.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ The &gdk-pixbuf; library provides a simple mechanism for loading
+ an image from a file in synchronous fashion. This means that the
+ library takes control of the application while the file is being
+ loaded; from the user's point of view, the application will block
+ until the image is done loading.
+ </para>
+
+ <para>
+ This interface can be used by applications in which blocking is
+ acceptable while an image is being loaded. It can also be used to
+ load small images in general. Applications that need progressive
+ loading can use the #GdkPixbufLoader functionality instead.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ #GdkPixbufLoader.
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_new_from_file ##### -->
<para>
@filename:
@error:
-@Returns:
+@Returns: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
-<!-- ##### SECTION ./tmpl/from-drawables.sgml:Title ##### -->
-Drawables to Pixbufs
+<!-- ##### SECTION ./tmpl/animation.sgml:Long_Description ##### -->
+ <para>
+ The &gdk-pixbuf; library provides a simple mechanism to load and
+ represent animations, primarily animated GIF files. Animations
+ are represented as lists of #GdkPixbufFrame structures. Each
+ frame structure contains a #GdkPixbuf structure and information
+ about the frame's overlay mode and duration.
+ </para>
-<!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
+<!-- ##### SECTION ./tmpl/animation.sgml:See_Also ##### -->
<para>
- A function of this type can be used to override the default
- operation when a pixbuf loses its last reference, i.e. when
- gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
- reference count of 1. This function should determine whether to
- finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
- to just resume normal execution. The last unref handler for a
- #GdkPixbuf can be set using the
- gdk_pixbuf_set_last_unref_handler() function. By default, pixbufs
- will be finalized automatically if no last unref handler has been
- defined.
+ #GdkPixbufLoader
</para>
-@pixbuf: The pixbuf that is losing its last reference.
-@data: User closure data.
-<!-- ##### FUNCTION gdk_pixbuf_frame_copy ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/animation.sgml:Short_Description ##### -->
+Animations as multi-frame structures.
-</para>
-@src:
-@Returns:
-@frame:
+<!-- ##### SECTION ./tmpl/animation.sgml:Title ##### -->
+Animations
-<!-- ##### SECTION ./tmpl/rendering.sgml:See_Also ##### -->
+
+<!-- ##### SECTION ./tmpl/from-drawables.sgml:Long_Description ##### -->
<para>
- GdkRGB
+ The functions in this section allow you to take the image data
+ from a GDK drawable and dump it into a #GdkPixbuf. This can be
+ used for screenshots and other special effects. Note that these
+ operations can be expensive, since the image data has to be
+ transferred from the X server to the client program and converted.
</para>
-<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Title ##### -->
-X Drawables to Pixbufs
-
+<!-- ##### SECTION ./tmpl/from-drawables.sgml:See_Also ##### -->
+ <para>
+ gdk_image_get().
+ </para>
-<!-- ##### FUNCTION gdk_pixbuf_render_pixmap_and_mask ##### -->
-<para>
-</para>
+<!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
+Getting parts of a drawable's image data into a pixbuf.
-@pixbuf:
-@pixmap_return:
-@mask_return:
-@alpha_threshold: <!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
- <para>
- Indicates the width the pixbuf will be scaled to. This argument
- will only be used if the <link
- linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
- is %TRUE. If the <link
- linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
- argument is %FALSE, the width will be taken to be in canvas units,
- and thus will be scaled along with the canvas item's affine
- transformation. If width_in_pixels is %TRUE, the width will be
- taken to be in pixels, and will visually remain a constant size
- even if the item's affine transformation changes.
- </para>
+<!-- ##### SECTION ./tmpl/from-drawables.sgml:Title ##### -->
+Drawables to Pixbufs
-<!-- ##### ARG GnomeCanvasPixbuf:x-pixels ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:See_Also ##### -->
<para>
</para>
-@pixbuf:
-@drawable:
-@gc:
-@src_x:
-@src_y:
-@dest_x:
-@dest_y:
-@width:
-@height:
-@dither:
-@x_dither:
-@y_dither:
-<!-- ##### FUNCTION gdk_pixbuf_get_from_drawable ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Short_Description ##### -->
-</para>
-@dest:
-@src:
-@cmap:
-@src_x:
-@src_y:
-@dest_x:
-@dest_y:
-@width:
-@height:
-@Returns: <!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Title ##### -->
+gdk-pixbuf-io
+
+
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-loader.sgml:Long_Description ##### -->
<para>
- Indicates the horizontal translation offset of the pixbuf item's
- image. This offset may not actually appear horizontal, since it
- will be affected by the item's affine transformation. The default
- is 0.0.
+ #GdkPixbufLoader provides a way for applications to drive the
+ process of loading an image, by letting them send the image data
+ directly to the loader instead of having the loader read the data
+ from a file. Applications can use this functionality instead of
+ gdk_pixbuf_new_from_file() when they need to parse image data in
+ small chunks. For example, it should be used when reading an
+ image from a (potentially) slow network connection, or when
+ loading an extremely large file.
</para>
+ <para>
+ To use #GdkPixbufLoader to load an image, just create a new one,
+ and call gdk_pixbuf_loader_write() to send the data to it. When
+ done, gdk_pixbuf_loader_close() should be called to end the stream
+ and finalize everything. The loader will emit two important
+ signals throughout the process. The first, "<link
+ linkend="GdkPixbufLoader-area-prepared">area_prepared</link>",
+ will be called as soon as the image has enough information to
+ determine the size of the image to be used. It will pass a
+ @GdkPixbuf in. If you want to use it, you can simply ref it. In
+ addition, no actual information will be passed in yet, so the
+ pixbuf can be safely filled with any temporary graphics (or an
+ initial color) as needed. You can also call the
+ gdk_pixbuf_loader_get_pixbuf() once this signal has been emitted
+ and get the same pixbuf.
+ </para>
-<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
<para>
- Indicates the vertical translation offset of the pixbuf item's
- image. Works in the same way as the <link
- linkend="GnomeCanvasPixbuf--x">x</link> argument. The default is
- 0.0.
+ The other signal, "<link
+ linkend="GdkPixbufLoader-area-updated">area_updated</link>" gets
+ called every time a region is updated. This way you can update a
+ partially completed image. Note that you do not know anything
+ about the completeness of an image from the area updated. For
+ example, in an interlaced image, you need to make several passes
+ before the image is done loading.
</para>
+ <refsect2>
+ <title>Loading an animation</title>
-<!-- ##### SECTION ./tmpl/xlib-init.sgml:Short_Description ##### -->
-Initializing the &gdk-pixbuf; Xlib library.
+ <para>
+ Loading an animation is a little more complex then loading an
+ image. In addition to the above signals, there is also a "<link
+ linkend="GdkPixbufLoader-frame-done">frame_done</link>" signal,
+ as well as an "<link
+ linkend="GdkPixbufLoader-animation-done">animation_done</link>"
+ signal. The first lets the application know that it is dealing
+ with an animation, instead of a static image. It also passes a
+ #GdkPixbufFrame in the signal. As before, if you want to keep
+ the frame, you need to ref it. Once the first "<link
+ linkend="GdkPixbufLoader-frame-done">frame_done</link>" signal
+ has been emitted, you can call gdk_pixbuf_loader_get_animation()
+ to get the #GdkPixbufAnimation struct. Each subsequent frame
+ goes through a similar lifecycle. For example "<link
+ linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" is
+ re-emitted. Then "<link
+ linkend="GdkPixbufLoader-area-updated">area_updated</link>" is
+ emitted as many times as necessary. Finally, "<link
+ linkend="GdkPixbufLoader-animation-done">animation_done</link>"
+ is emitted as soon as all frames are done.
+ </para>
+ </refsect2>
-<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-loader.sgml:See_Also ##### -->
+ <para>
+ gdk_pixbuf_new_from_file()
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-loader.sgml:Short_Description ##### -->
+Application-driven progressive image loading.
+
+
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-loader.sgml:Title ##### -->
+GdkPixbufLoader
+
+
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-from-drawables.sgml:Long_Description ##### -->
<para>
The functions in this section allow you to take the image data
from an X drawable and dump it into a #GdkPixbuf. This can be
</para>
-<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-from-drawables.sgml:See_Also ##### -->
<para>
</para>
-@art_pixbuf:
-@Returns:
-<!-- ##### SECTION ./tmpl/xlib-init.sgml:See_Also ##### -->
- <para>
- XlibRGB
- </para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-from-drawables.sgml:Short_Description ##### -->
+Getting parts of an X drawable's image data into a pixbuf.
-<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:See_Also ##### -->
- <para>
- #GnomeCanvas, #GdkPixbuf
- </para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-from-drawables.sgml:Title ##### -->
+X Drawables to Pixbufs
-<!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-init.sgml:Long_Description ##### -->
<para>
- Contains a pointer to a #GdkPixbuf structure that will be used by
- the pixbuf canvas item as an image source. When a pixbuf is set
- its reference count is incremented; if the pixbuf item kept a
- pointer to another #GdkPixbuf structure, the reference count of
- this structure will be decremented. Also, the GdkPixbuf's
- reference count will automatically be decremented when the
- #GnomeCanvasPixbuf item is destroyed. When a pixbuf is queried, a
- reference count will not be added to the return value; you must do
- this yourself if you intend to keep the pixbuf structure around.
+ In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
+ package provides a small library that lets Xlib-only applications
+ use #GdkPixbuf structures and render them to X drawables. The
+ functions in this section are used to initialize the &gdk-pixbuf;
+ Xlib library. This library must be initialized near the beginning
+ or the program or before calling any of the other &gdk-pixbuf;
+ Xlib functions; it cannot be initialized automatically since
+ Xlib-only applications do not call gdk_rgb_init() like GNOME
+ applications do.
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:width-pixels ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-init.sgml:See_Also ##### -->
<para>
- GdkRGB
+ XlibRGB
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:x-set ##### -->
- <para>
- Determines whether the <link
- linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
- translate the pixbuf from its logical origin in item-relative
- coordinates.
- </para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-init.sgml:Short_Description ##### -->
+Initializing the &gdk-pixbuf; Xlib library.
-<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-init.sgml:Title ##### -->
+&gdk-pixbuf; Xlib initialization
+
+
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rendering.sgml:Long_Description ##### -->
<para>
The &gdk-pixbuf; Xlib library provides several convenience
functions to render pixbufs to X drawables. It uses XlibRGB to
</para>
-<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Short_Description ##### -->
-
-
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rendering.sgml:See_Also ##### -->
+<para>
-<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Short_Description ##### -->
-Canvas item to display #GdkPixbuf images.
+</para>
-<!-- ##### SECTION ./tmpl/from-drawables.sgml:Long_Description ##### -->
- <para>
- The functions in this section allow you to take the image data
- from a GDK drawable and dump it into a #GdkPixbuf. This can be
- used for screenshots and other special effects. Note that these
- operations can be expensive, since the image data has to be
- transferred from the X server to the client program and converted.
- </para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rendering.sgml:Short_Description ##### -->
+Rendering a pixbuf to an X drawable.
-<!-- ##### ARG GnomeCanvasPixbuf:width-set ##### -->
- <para>
- Determines whether the <link
- linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
- into account when scaling the pixbuf item. If this argument is
- %FALSE, then the width value of the pixbuf will be used instead.
- This argument is %FALSE by default.
- </para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rendering.sgml:Title ##### -->
+Xlib Rendering
-<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rgb.sgml:Long_Description ##### -->
<para>
The XlibRGB set of functions is a port of the GdkRGB library to
use plain Xlib and X drawables. You can use these functions to
</para>
-<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Short_Description ##### -->
-Functions for rendering RGB buffers to X drawables.
-
-
-<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rgb.sgml:See_Also ##### -->
<para>
- Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
+ GdkRGB
</para>
-@obj: A GTK+ object.
-
-<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:See_Also ##### -->
-<para>
-
-</para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rgb.sgml:Short_Description ##### -->
+Functions for rendering RGB buffers to X drawables.
-<!-- ##### ARG GnomeCanvasPixbuf:height-pixels ##### -->
-<para>
-</para>
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-xlib-rgb.sgml:Title ##### -->
+XlibRGB
-<!-- ##### ARG GnomeCanvasPixbuf:y-in-pixels ##### -->
+<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
<para>
- Works in the same way as the <link
- linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
- argument, but controls whether the <link
- linkend="GnomeCanvasPixbuf--y">y</link> translation offset is
- scaled or not. The default is %FALSE.
+ This canvas item displays #GdkPixbuf images. It handles full
+ affine transformations in both GDK and antialiased modes, and also
+ supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
+ url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
+ translation semantics for absolute pixel values.
</para>
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
+ <para>
+ #GdkPixbuf structures may be shared among different pixbuf canvas
+ items; the pixbuf item uses #GdkPixbuf's reference counting
+ functions for this.
+ </para>
+ <refsect2>
+ <title>Custom Scaling and Translation</title>
-<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Short_Description ##### -->
-Rendering a pixbuf to an X drawable.
+ <para>
+ In addition to the normal affine transformations supported by
+ canvas items, the #GnomeCanvasPixbuf item supports independent
+ object arguments for scaling and translation. This is useful
+ for explicitly setting a size to which the pixbuf's image will
+ be scaled, and for specifying translation offsets that take
+ place in the item's local coordinate system.
+ </para>
+ <para>
+ By default, the pixbuf canvas item will attain the size in units
+ of the #GdkPixbuf it contains. If a #GnomeCanvasPixbuf is
+ configured to use a #GdkPixbuf that has a size of 300 by 200
+ pixels, then the pixbuf item will automatically obtain a size of
+ 300 by 200 units in the item's local coordinate system. If the
+ item is transformed with a scaling transformation of (0.5, 2.0),
+ then the final image size will be of 150 by 400 pixels.
+ </para>
-<!-- ##### FUNCTION gdk_pixbuf_finalize ##### -->
+ <para>
+ To set custom width and height values, you must set the <link
+ linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
+ linkend="GnomeCanvasPixbuf--height-set">height_set</link>
+ arguments to %TRUE, and then set the <link
+ linkend="GnomeCanvasPixbuf--width">width</link> or <link
+ linkend="GnomeCanvasPixbuf--height">height</link> arguments to
+ the desired values. The former two arguments control whether
+ the latter two are used when computing the final image's size;
+ they are both %FALSE by default so that the pixbuf item will
+ attain a size in units equal to the size in pixels of the
+ #GdkPixbuf that the item contains.
+ </para>
+
+ <para>
+ The custom translation offsets are controlled by the <link
+ linkend="GnomeCanvasPixbuf--x">x</link> and <link
+ linkend="GnomeCanvasPixbuf--y">y</link> arguments. The logical
+ upper-left vertex of the image will be translated by the
+ specified distance, aligned with the item's local coordinate
+ system.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Absolute Pixel Scaling and Translation</title>
+
+ <para>
+ The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
+ Graphics</ulink> specification (SVG) of the <ulink
+ url="http://www.w3.org">World Wide Web Consortium</ulink> also
+ allows images to be translated and scaled by absolute pixel
+ values that are independent of an item's normal affine
+ transformation.
+ </para>
+
+ <para>
+ Normally, the pixbuf item's translation and scaling arguments
+ are interpreted in units, so they will be modified by the item's
+ affine transformation. The <link
+ linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
+ <link
+ linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
+ <link
+ linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
+ <link
+ linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
+ object arguments can be used to modify this behavior. If one of
+ these arguments is %TRUE, then the corresponding scaling or
+ translation value will not be affected lengthwise by the pixbuf
+ item's affine transformation.
+ </para>
+
+ <para>
+ For example, consider a pixbuf item whose size is (300, 200).
+ If the item is modified with a scaling transformation of (0.5,
+ 2.0) but the <link
+ linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
+ is set to %TRUE, then the item will appear to be (300, 400)
+ pixels in size. This means that in this case the item's affine
+ transformation only applies to the height value, while the width
+ value is kept in absolute pixels.
+ </para>
+
+ <para>
+ Likewise, consider a pixbuf item whose (<link
+ linkend="GnomeCanvasPixbuf--x">x</link>, <link
+ linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
+ (30, 40). If the item is then modified by the same scaling
+ transformation of (0.5, 2.0) but the <link
+ linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
+ argument is set to %TRUE, then the image's upper-left corner
+ will appear to be at position (15, 40). In this case, the
+ affine transformation is applied only to the x offset, while the
+ y offset is kept in absolute pixels.
+ </para>
+
+ <para>
+ In short, these arguments control whether a particular dimension
+ of a pixbuf item is scaled or not in the normal way by the
+ item's affine transformation.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Resource Management</title>
+
+ <para>
+ When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
+ item will use by setting the <link
+ linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
+ reference count will be added to that #GdkPixbuf structure.
+ When the pixbuf item no longer needs the #GdkPixbuf structure,
+ such as when the item is destroyed or when a new pixbuf
+ structure is passed to it, then the old #GdkPixbuf structure
+ will be automatically unreferenced.
+ </para>
+
+ <para>
+ This means that if an application just needs to load a pixbuf
+ image and set it into a pixbuf canvas item, it can do the
+ following to ‘forget’ about the pixbuf structure:
+
+ <programlisting>
+ GdkPixbuf *pixbuf;
+ GnomeCanvasItem *item;
+
+ pixbuf = gdk_pixbuf_new_from_file ("foo.png");
+ g_assert (pixbuf != NULL);
+
+ item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
+ gnome_canvas_pixbuf_get_type (),
+ "pixbuf", pixbuf,
+ NULL);
+ gdk_pixbuf_unref (pixbuf);
+ </programlisting>
+ </para>
+
+ <para>
+ After this happens, the reference count of the pixbuf structure
+ will be 1: the gdk_pixbuf_new_from_file() function creates it
+ with a reference count of 1, then setting the <link
+ linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
+ the #GnomeCanvasPixbuf item increases it to 2, and then it is
+ decremented to 1 by the call to gdk_pixbuf_unref(). When the
+ canvas item is destroyed, it will automatically unreference the
+ pixbuf structure again, causing its reference count to drop to
+ zero and thus be freed.
+ </para>
+ </refsect2>
+
+
+<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:See_Also ##### -->
+ <para>
+ #GnomeCanvas, #GdkPixbuf
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Short_Description ##### -->
+Canvas item to display #GdkPixbuf images.
+
+
+<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
+GnomeCanvasPixbuf
+
+
+<!-- ##### SECTION ./tmpl/module_interface.sgml:Long_Description ##### -->
<para>
</para>
-@pixbuf: <!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-<!-- ##### ARG GnomeCanvasPixbuf:x-in-pixels ##### -->
+<!-- ##### SECTION ./tmpl/module_interface.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/module_interface.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/module_interface.sgml:Title ##### -->
+Module Interface
+
+
+<!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
+ <para>
+ The &gdk-pixbuf; library provides several convenience functions to
+ render pixbufs to GDK drawables. It uses the GdkRGB to render the
+ image data.
+ </para>
+
+ <para>
+ At this point there is not a standard alpha channel extension for
+ the X Window System, so it is not possible to use full opacity
+ information when painting images to arbitrary drawables. The
+ &gdk-pixbuf; convenience functions will threshold the opacity
+ information to create a bi-level clipping mask (black and white),
+ and use that to draw the image onto a drawable.
+ </para>
+
+ <important>
+ <para>
+ Since these functions use GdkRGB for rendering, you must
+ initialize GdkRGB before using any of them. You can do this by
+ calling gdk_rgb_init() near the beginning of your program.
+ </para>
+ </important>
+
+
+<!-- ##### SECTION ./tmpl/rendering.sgml:See_Also ##### -->
+ <para>
+ GdkRGB
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/rendering.sgml:Short_Description ##### -->
+Rendering a pixbuf to a GDK drawable.
+
+
+<!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
+Rendering
+
+
+<!-- ##### SECTION ./tmpl/scaling.sgml:Long_Description ##### -->
+ <para>
+ The &gdk-pixbuf; contains functions to scale pixbufs, to scale
+ pixbufs and composite against an existing image, and to scale
+ pixbufs and composite against a solid color or checkerboard.
+ Compositing a checkerboard is a common way to show an image with
+ an alpha channel in image-viewing and editing software.
+ </para>
+
+ <para>
+ Since the full-featured functions (gdk_pixbuf_scale(),
+ gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are
+ rather complex to use and have many arguments, two simple
+ convenience functions are provided, gdk_pixbuf_scale_simple() and
+ gdk_pixbuf_composite_color_simple() which create a new pixbuf of a
+ given size, scale an original image to fit, and then return the
+ new pixmap.
+ </para>
+
+ <para>
+ The following example demonstrates handling an expose event by
+ rendering the appropriate area of a source image (which is scaled
+ to fit the widget) onto the widget's window. The source image is
+ rendered against a checkerboard, which provides a visual
+ representation of the alpha channel if the image has one. If the
+ image doesn't have an alpha channel, calling
+ gdk_pixbuf_composite_color() function has exactly the same effect
+ as calling gdk_pixbuf_scale().
+ </para>
+
+ <programlisting>
+gboolean
+expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
+{
+ GdkPixbuf *dest;
+
+ gdk_window_set_back_pixmap (widget->window, NULL, FALSE);
+
+ dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);
+
+ gdk_pixbuf_composite_color (pixbuf, dest,
+ 0, 0, event->area.width, event->area.height,
+ -event->area.x, -event->area.y,
+ (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
+ (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
+ GDK_INTERP_BILINEAR, 255,
+ event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);
+
+ gdk_pixbuf_render_to_drawable (dest, widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
+ 0, 0, event->area.x, event->area.y,
+ event->area.width, event->area.height,
+ GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);
+
+ gdk_pixbuf_unref (dest);
+
+ return TRUE;
+}
+ </programlisting>
+
+
+<!-- ##### SECTION ./tmpl/scaling.sgml:See_Also ##### -->
+ <para>
+ GdkRGB
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/scaling.sgml:Short_Description ##### -->
+Scaling pixbufs and scaling and compositing pixbufs
+
+
+<!-- ##### SECTION ./tmpl/scaling.sgml:Title ##### -->
+Scaling
+
+
+<!-- ##### SECTION ./tmpl/util.sgml:Long_Description ##### -->
+ <para>
+ These functions provide miscellaneous utilities for manipulating
+ pixbufs. The pixel data in pixbufs may of course be manipulated
+ directly by applications, but several common operations can be
+ performed by these functions instead.
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/util.sgml:See_Also ##### -->
+ <para>
+ #GdkPixbuf
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/util.sgml:Short_Description ##### -->
+Utility and miscellaneous convenience functions.
+
+
+<!-- ##### SECTION ./tmpl/util.sgml:Title ##### -->
+Utilities
+
+
+<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Long_Description ##### -->
+ <para>
+ The functions in this section allow you to take the image data
+ from an X drawable and dump it into a #GdkPixbuf. This can be
+ used for screenshots and other special effects. Note that these
+ operations can be expensive, since the image data has to be
+ transferred from the X server to the client program and converted.
+ </para>
+
+ <para>
+ These functions are analogous to those for the Gdk version of
+ &gdk-pixbuf;.
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Short_Description ##### -->
+Getting parts of an X drawable's image data into a pixbuf.
+
+
+<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Title ##### -->
+X Drawables to Pixbufs
+
+
+<!-- ##### SECTION ./tmpl/xlib-init.sgml:Long_Description ##### -->
+ <para>
+ In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
+ package provides a small library that lets Xlib-only applications
+ use #GdkPixbuf structures and render them to X drawables. The
+ functions in this section are used to initialize the &gdk-pixbuf;
+ Xlib library. This library must be initialized near the beginning
+ or the program or before calling any of the other &gdk-pixbuf;
+ Xlib functions; it cannot be initialized automatically since
+ Xlib-only applications do not call gdk_rgb_init() like GNOME
+ applications do.
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-init.sgml:See_Also ##### -->
+ <para>
+ XlibRGB
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-init.sgml:Short_Description ##### -->
+Initializing the &gdk-pixbuf; Xlib library.
+
+
+<!-- ##### SECTION ./tmpl/xlib-init.sgml:Title ##### -->
+&gdk-pixbuf; Xlib initialization
+
+
+<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Long_Description ##### -->
+ <para>
+ The &gdk-pixbuf; Xlib library provides several convenience
+ functions to render pixbufs to X drawables. It uses XlibRGB to
+ render the image data.
+ </para>
+
+ <para>
+ These functions are analogous to those for the Gdk version of
+ &gdk-pixbuf;.
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Short_Description ##### -->
+Rendering a pixbuf to an X drawable.
+
+
+<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
+Xlib Rendering
+
+
+<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Long_Description ##### -->
+ <para>
+ The XlibRGB set of functions is a port of the GdkRGB library to
+ use plain Xlib and X drawables. You can use these functions to
+ render RGB buffers into drawables very quickly with high-quality
+ dithering.
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:See_Also ##### -->
+ <para>
+ GdkRGB
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Short_Description ##### -->
+Functions for rendering RGB buffers to X drawables.
+
+
+<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
+XlibRGB
+
+
+<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
+ <para>
+ Casts a #GtkObject to a #GdkPixbufLoader.
+ </para>
+
+@obj: A GTK+ object.
+
+<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
<para>
- If this argument is %TRUE, the pixbuf's translation with respect
- to its logical origin in item-relative coordinates will be in
- pixels, that is, the visible offset will not change even if the
- item's affine transformation changes. If it is %FALSE, the
- pixbuf's translation will be taken to be in canvas units, and thus
- will change along with the item's affine transformation. The
- default is %FALSE.
+ Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
</para>
+@obj: A GTK+ object.
-<!-- ##### SECTION ./tmpl/rendering.sgml:Short_Description ##### -->
-Rendering a pixbuf to a GDK drawable.
+<!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
+<para>
+</para>
-<!-- ##### FUNCTION gdk_pixbuf_set_last_unref_handler ##### -->
+
+<!-- ##### STRUCT GdkPixbufClass ##### -->
<para>
</para>
-@pixbuf:
-@last_unref_fn:
-@last_unref_fn_data:
-<!-- ##### ARG GnomeCanvasPixbuf:y-set ##### -->
+<!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
<para>
- Determines whether the <link
- linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
- translate the pixbuf from its logical origin in item-relative
- coordinates. Works in the same way as the <link
- linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument. The
- default is %FALSE.
+ A function of this type can be used to override the default
+ operation when a pixbuf loses its last reference, i.e. when
+ gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
+ reference count of 1. This function should determine whether to
+ finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
+ to just resume normal execution. The last unref handler for a
+ #GdkPixbuf can be set using the
+ gdk_pixbuf_set_last_unref_handler() function. By default, pixbufs
+ will be finalized automatically if no last unref handler has been
+ defined.
</para>
+@pixbuf: The pixbuf that is losing its last reference.
+@data: User closure data.
-<!-- ##### SECTION ./tmpl/xlib-init.sgml:Long_Description ##### -->
+<!-- ##### SIGNAL GdkPixbufLoader::animation-done ##### -->
<para>
- In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
- package provides a small library that lets Xlib-only applications
- use #GdkPixbuf structures and render them to X drawables. The
- functions in this section are used to initialize the &gdk-pixbuf;
- Xlib library. This library must be initialized near the beginning
- or the program or before calling any of the other &gdk-pixbuf;
- Xlib functions; it cannot be initialized automatically since
- Xlib-only applications do not call gdk_rgb_init() like GNOME
- applications do.
+ This signal is emitted when an animation is done loading.
</para>
+@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
-<!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
-<para>
+<!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
+ <para>
+ This signal is emitted when the pixbuf loader has been fed the
+ initial amount of data that is required to figure out the size and
+ format of the image that it will create. After this signal is
+ emitted, applications can call gdk_pixbuf_loader_get_pixbuf() to
+ fetch the partially-loaded pixbuf.
+ </para>
-</para>
+@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
-@pixbuf:
-@Returns:
+<!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
+ <para>
+ This signal is emitted when a significant area of the image being
+ loaded has been updated. Normally it means that a complete
+ scanline has been read in, but it could be a different area as
+ well. Applications can use this signal to know when to repaint
+ areas of an image that is being loaded.
+ </para>
-<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:See_Also ##### -->
-<para>
+@gdkpixbufloader: the object which received the signal.
+@arg1:
+@arg2:
+@arg3:
+@arg4:
+@loader: Loader which emitted the signal.
+@x: X offset of upper-left corner of the updated area.
+@y: Y offset of upper-left corner of the updated area.
+@width: Width of updated area.
+@height: Height of updated area.
+
+<!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
+ <para>
+ This signal is emitted when gdk_pixbuf_loader_close() is called.
+ It can be used by different parts of an application to receive
+ notification when an image loader is closed by the code that
+ drives it.
+ </para>
-</para>
+@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
-<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable_alpha ##### -->
-<para>
+<!-- ##### SIGNAL GdkPixbufLoader::frame-done ##### -->
+ <para>
+ This signal is emitted when a frame is done loading. It will be
+ emitted for each frame in an animation data stream.
+ </para>
-</para>
+@gdkpixbufloader: the object which received the signal.
+@arg1:
+@loader: Loader which emitted the signal.
+@frame: Frame which just completed loading.
-@pixbuf:
-@drawable:
-@src_x:
-@src_y:
-@dest_x:
-@dest_y:
-@width:
-@height:
-@alpha_mode:
-@alpha_threshold:
-@dither:
-@x_dither:
-@y_dither:
+<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
+ <para>
+ Indicates the height the pixbuf will be scaled to. This argument
+ will only be used if the <link
+ linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
+ is %TRUE. Works in the same way as the <link
+ linkend="GnomeCanvasPixbuf--width">width</link> argument.
+ </para>
-<!-- ##### ARG GnomeCanvasPixbuf:y-pixels ##### -->
-<para>
-</para>
+<!-- ##### ARG GnomeCanvasPixbuf:height-in-pixels ##### -->
+ <para>
+ Works in the same way as the <link
+ linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
+ argument. The default is %FALSE.
+ </para>
-<!-- ##### SECTION ./tmpl/xlib-init.sgml:Title ##### -->
-&gdk-pixbuf; Xlib initialization
+<!-- ##### ARG GnomeCanvasPixbuf:height-pixels ##### -->
+<para>
+
+</para>
<!-- ##### ARG GnomeCanvasPixbuf:height-set ##### -->
</para>
-<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Short_Description ##### -->
-Getting parts of an X drawable's image data into a pixbuf.
+<!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
+ <para>
+ Contains a pointer to a #GdkPixbuf structure that will be used by
+ the pixbuf canvas item as an image source. When a pixbuf is set
+ its reference count is incremented; if the pixbuf item kept a
+ pointer to another #GdkPixbuf structure, the reference count of
+ this structure will be decremented. Also, the GdkPixbuf's
+ reference count will automatically be decremented when the
+ #GnomeCanvasPixbuf item is destroyed. When a pixbuf is queried, a
+ reference count will not be added to the return value; you must do
+ this yourself if you intend to keep the pixbuf structure around.
+ </para>
-<!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
-XlibRGB
+<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+ <para>
+ Indicates the width the pixbuf will be scaled to. This argument
+ will only be used if the <link
+ linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
+ is %TRUE. If the <link
+ linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
+ argument is %FALSE, the width will be taken to be in canvas units,
+ and thus will be scaled along with the canvas item's affine
+ transformation. If width_in_pixels is %TRUE, the width will be
+ taken to be in pixels, and will visually remain a constant size
+ even if the item's affine transformation changes.
+ </para>
<!-- ##### ARG GnomeCanvasPixbuf:width-in-pixels ##### -->
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:width-pixels ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GnomeCanvasPixbuf:width-set ##### -->
<para>
- Indicates the height the pixbuf will be scaled to. This argument
- will only be used if the <link
- linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
- is %TRUE. Works in the same way as the <link
- linkend="GnomeCanvasPixbuf--width">width</link> argument.
+ Determines whether the <link
+ linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
+ into account when scaling the pixbuf item. If this argument is
+ %FALSE, then the width value of the pixbuf will be used instead.
+ This argument is %FALSE by default.
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:height-in-pixels ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
<para>
- Works in the same way as the <link
- linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
- argument. The default is %FALSE.
+ Indicates the horizontal translation offset of the pixbuf item's
+ image. This offset may not actually appear horizontal, since it
+ will be affected by the item's affine transformation. The default
+ is 0.0.
</para>
-<!-- ##### SECTION ./tmpl/from-drawables.sgml:See_Also ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x-in-pixels ##### -->
<para>
- gdk_image_get().
+ If this argument is %TRUE, the pixbuf's translation with respect
+ to its logical origin in item-relative coordinates will be in
+ pixels, that is, the visible offset will not change even if the
+ item's affine transformation changes. If it is %FALSE, the
+ pixbuf's translation will be taken to be in canvas units, and thus
+ will change along with the item's affine transformation. The
+ default is %FALSE.
</para>
-<!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x-pixels ##### -->
<para>
</para>
-<!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
-<para>
+<!-- ##### ARG GnomeCanvasPixbuf:x-set ##### -->
+ <para>
+ Determines whether the <link
+ linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
+ translate the pixbuf from its logical origin in item-relative
+ coordinates.
+ </para>
-</para>
+<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
+ <para>
+ Indicates the vertical translation offset of the pixbuf item's
+ image. Works in the same way as the <link
+ linkend="GnomeCanvasPixbuf--x">x</link> argument. The default is
+ 0.0.
+ </para>
-<!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
-Rendering
+<!-- ##### ARG GnomeCanvasPixbuf:y-in-pixels ##### -->
+ <para>
+ Works in the same way as the <link
+ linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
+ argument, but controls whether the <link
+ linkend="GnomeCanvasPixbuf--y">y</link> translation offset is
+ scaled or not. The default is %FALSE.
+ </para>
-<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
-GnomeCanvasPixbuf
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
-<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
- <para>
- Casts a #GtkObject to a #GdkPixbufLoader.
- </para>
+<!-- ##### ARG GnomeCanvasPixbuf:y-pixels ##### -->
+<para>
-@obj: A GTK+ object.
+</para>
-<!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
- <para>
- The &gdk-pixbuf; library provides several convenience functions to
- render pixbufs to GDK drawables. It uses the GdkRGB to render the
- image data.
- </para>
+<!-- ##### ARG GnomeCanvasPixbuf:y-set ##### -->
<para>
- At this point there is not a standard alpha channel extension for
- the X Window System, so it is not possible to use full opacity
- information when painting images to arbitrary drawables. The
- &gdk-pixbuf; convenience functions will threshold the opacity
- information to create a bi-level clipping mask (black and white),
- and use that to draw the image onto a drawable.
+ Determines whether the <link
+ linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
+ translate the pixbuf from its logical origin in item-relative
+ coordinates. Works in the same way as the <link
+ linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument. The
+ default is %FALSE.
</para>
- <important>
- <para>
- Since these functions use GdkRGB for rendering, you must
- initialize GdkRGB before using any of them. You can do this by
- calling gdk_rgb_init() near the beginning of your program.
- </para>
- </important>
+<!-- ##### FUNCTION gdk_pixbuf_finalize ##### -->
+<para>
+
+</para>
+
+@pixbuf: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
-<!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
-Getting parts of a drawable's image data into a pixbuf.
+<!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
+<para>
+</para>
-<!-- ##### FUNCTION gdk_pixbuf_render_threshold_alpha ##### -->
+@pixbuf:
+@Returns:
+
+<!-- ##### FUNCTION gdk_pixbuf_get_from_drawable ##### -->
<para>
</para>
-@pixbuf:
-@bitmap:
+@dest:
+@src:
+@cmap:
@src_x:
@src_y:
@dest_x:
@dest_y:
@width:
@height:
-@alpha_threshold:
+@Returns: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
-<!-- ##### STRUCT GdkPixbufClass ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_init ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Long_Description ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
<para>
</para>
+@art_pixbuf:
+@Returns:
-<!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
- <para>
- This canvas item displays #GdkPixbuf images. It handles full
- affine transformations in both GDK and antialiased modes, and also
- supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
- url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
- translation semantics for absolute pixel values.
- </para>
-
- <para>
- #GdkPixbuf structures may be shared among different pixbuf canvas
- items; the pixbuf item uses #GdkPixbuf's reference counting
- functions for this.
- </para>
-
- <refsect2>
- <title>Custom Scaling and Translation</title>
-
- <para>
- In addition to the normal affine transformations supported by
- canvas items, the #GnomeCanvasPixbuf item supports independent
- object arguments for scaling and translation. This is useful
- for explicitly setting a size to which the pixbuf's image will
- be scaled, and for specifying translation offsets that take
- place in the item's local coordinate system.
- </para>
-
- <para>
- By default, the pixbuf canvas item will attain the size in units
- of the #GdkPixbuf it contains. If a #GnomeCanvasPixbuf is
- configured to use a #GdkPixbuf that has a size of 300 by 200
- pixels, then the pixbuf item will automatically obtain a size of
- 300 by 200 units in the item's local coordinate system. If the
- item is transformed with a scaling transformation of (0.5, 2.0),
- then the final image size will be of 150 by 400 pixels.
- </para>
-
- <para>
- To set custom width and height values, you must set the <link
- linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
- linkend="GnomeCanvasPixbuf--height-set">height_set</link>
- arguments to %TRUE, and then set the <link
- linkend="GnomeCanvasPixbuf--width">width</link> or <link
- linkend="GnomeCanvasPixbuf--height">height</link> arguments to
- the desired values. The former two arguments control whether
- the latter two are used when computing the final image's size;
- they are both %FALSE by default so that the pixbuf item will
- attain a size in units equal to the size in pixels of the
- #GdkPixbuf that the item contains.
- </para>
+<!-- ##### FUNCTION gdk_pixbuf_postinit ##### -->
+<para>
- <para>
- The custom translation offsets are controlled by the <link
- linkend="GnomeCanvasPixbuf--x">x</link> and <link
- linkend="GnomeCanvasPixbuf--y">y</link> arguments. The logical
- upper-left vertex of the image will be translated by the
- specified distance, aligned with the item's local coordinate
- system.
- </para>
- </refsect2>
+</para>
- <refsect2>
- <title>Absolute Pixel Scaling and Translation</title>
+@app:
+@modinfo:
- <para>
- The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
- Graphics</ulink> specification (SVG) of the <ulink
- url="http://www.w3.org">World Wide Web Consortium</ulink> also
- allows images to be translated and scaled by absolute pixel
- values that are independent of an item's normal affine
- transformation.
- </para>
+<!-- ##### FUNCTION gdk_pixbuf_preinit ##### -->
+<para>
- <para>
- Normally, the pixbuf item's translation and scaling arguments
- are interpreted in units, so they will be modified by the item's
- affine transformation. The <link
- linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
- <link
- linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
- <link
- linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
- <link
- linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
- object arguments can be used to modify this behavior. If one of
- these arguments is %TRUE, then the corresponding scaling or
- translation value will not be affected lengthwise by the pixbuf
- item's affine transformation.
- </para>
+</para>
- <para>
- For example, consider a pixbuf item whose size is (300, 200).
- If the item is modified with a scaling transformation of (0.5,
- 2.0) but the <link
- linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
- is set to %TRUE, then the item will appear to be (300, 400)
- pixels in size. This means that in this case the item's affine
- transformation only applies to the height value, while the width
- value is kept in absolute pixels.
- </para>
+@app:
+@modinfo:
- <para>
- Likewise, consider a pixbuf item whose (<link
- linkend="GnomeCanvasPixbuf--x">x</link>, <link
- linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
- (30, 40). If the item is then modified by the same scaling
- transformation of (0.5, 2.0) but the <link
- linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
- argument is set to %TRUE, then the image's upper-left corner
- will appear to be at position (15, 40). In this case, the
- affine transformation is applied only to the x offset, while the
- y offset is kept in absolute pixels.
- </para>
+<!-- ##### FUNCTION gdk_pixbuf_render_pixmap_and_mask ##### -->
+<para>
- <para>
- In short, these arguments control whether a particular dimension
- of a pixbuf item is scaled or not in the normal way by the
- item's affine transformation.
- </para>
- </refsect2>
+</para>
- <refsect2>
- <title>Resource Management</title>
+@pixbuf:
+@pixmap_return:
+@mask_return:
+@alpha_threshold: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
- <para>
- When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
- item will use by setting the <link
- linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
- reference count will be added to that #GdkPixbuf structure.
- When the pixbuf item no longer needs the #GdkPixbuf structure,
- such as when the item is destroyed or when a new pixbuf
- structure is passed to it, then the old #GdkPixbuf structure
- will be automatically unreferenced.
- </para>
+<!-- ##### FUNCTION gdk_pixbuf_render_threshold_alpha ##### -->
+<para>
- <para>
- This means that if an application just needs to load a pixbuf
- image and set it into a pixbuf canvas item, it can do the
- following to ‘forget’ about the pixbuf structure:
+</para>
- <programlisting>
- GdkPixbuf *pixbuf;
- GnomeCanvasItem *item;
+@pixbuf:
+@bitmap:
+@src_x:
+@src_y:
+@dest_x:
+@dest_y:
+@width:
+@height:
+@alpha_threshold:
- pixbuf = gdk_pixbuf_new_from_file ("foo.png");
- g_assert (pixbuf != NULL);
+<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable ##### -->
+<para>
- item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
- gnome_canvas_pixbuf_get_type (),
- "pixbuf", pixbuf,
- NULL);
- gdk_pixbuf_unref (pixbuf);
- </programlisting>
- </para>
+</para>
- <para>
- After this happens, the reference count of the pixbuf structure
- will be 1: the gdk_pixbuf_new_from_file() function creates it
- with a reference count of 1, then setting the <link
- linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
- the #GnomeCanvasPixbuf item increases it to 2, and then it is
- decremented to 1 by the call to gdk_pixbuf_unref(). When the
- canvas item is destroyed, it will automatically unreference the
- pixbuf structure again, causing its reference count to drop to
- zero and thus be freed.
- </para>
- </refsect2>
+@pixbuf:
+@drawable:
+@gc:
+@src_x:
+@src_y:
+@dest_x:
+@dest_y:
+@width:
+@height:
+@dither:
+@x_dither:
+@y_dither:
+<!-- ##### FUNCTION gdk_pixbuf_render_to_drawable_alpha ##### -->
+<para>
-<!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
-Xlib Rendering
+</para>
+@pixbuf:
+@drawable:
+@src_x:
+@src_y:
+@dest_x:
+@dest_y:
+@width:
+@height:
+@alpha_mode:
+@alpha_threshold:
+@dither:
+@x_dither:
+@y_dither:
-<!-- ##### FUNCTION gdk_pixbuf_frame_free ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_set_last_unref_handler ##### -->
<para>
</para>
-@frame:
-@src:
-
-<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Title ##### -->
-gdk-pixbuf-io
-
+@pixbuf:
+@last_unref_fn:
+@last_unref_fn_data:
<!-- ##### SECTION Title ##### -->
-gdk-pixbuf-xlib-init
+&gdk-pixbuf; Xlib initialization
<!-- ##### SECTION Short_Description ##### -->
-
+Initializing the &gdk-pixbuf; Xlib library.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
+ package provides a small library that lets Xlib-only applications
+ use #GdkPixbuf structures and render them to X drawables. The
+ functions in this section are used to initialize the &gdk-pixbuf;
+ Xlib library. This library must be initialized near the beginning
+ or the program or before calling any of the other &gdk-pixbuf;
+ Xlib functions; it cannot be initialized automatically since
+ Xlib-only applications do not call gdk_rgb_init() like GNOME
+ applications do.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ XlibRGB
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_xlib_init ##### -->
<para>
@display:
@screen_num:
-@prefDepth:
+@prefDepth: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
<!-- ##### SECTION Title ##### -->
-gdk-pixbuf
+The GdkPixbuf Structure
<!-- ##### SECTION Short_Description ##### -->
-
+Information that describes an image.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-</para>
+ <para>
+ The <structname>GdkPixbuf</structname> structure contains
+ information that describes an image in memory.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ <para>
+ </para>
<!-- ##### ENUM GdkPixbufError ##### -->
<para>
<!-- ##### ENUM GdkColorspace ##### -->
-<para>
-
-</para>
+ <para>
+ This enumeration defines the color spaces that are supported by
+ the &gdk-pixbuf; library. Currently only RGB is supported.
+ </para>
-@GDK_COLORSPACE_RGB:
+@GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
-<para>
-
-</para>
-
-@GDK_PIXBUF_ALPHA_BILEVEL:
-@GDK_PIXBUF_ALPHA_FULL:
+ <para>
+ These values can be passed to
+ gdk_pixbuf_render_to_drawable_alpha() to control how the alpha
+ chanel of an image should be handled. This function can create a
+ bilevel clipping mask (black and white) and use it while painting
+ the image. In the future, when the X Window System gets an alpha
+ channel extension, it will be possible to do full alpha
+ compositing onto arbitrary drawables. For now both cases fall
+ back to a bilevel clipping mask.
+ </para>
+
+@GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
+will be created and used to draw the image. Pixels below 0.5 opacity
+will be considered fully transparent, and all others will be
+considered fully opaque.
+@GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
+In the future it will do full alpha compositing.
<!-- ##### STRUCT GdkPixbuf ##### -->
-<para>
-
-</para>
+ <para>
+ This is the main structure in the &gdk-pixbuf; library. It is
+ used to represent images. It contains information about the
+ image's pixel data, its color space, bits per sample, width and
+ height, and the rowstride or number of bytes between rows.
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
</para>
@pixbuf:
-@Returns:
+@Returns: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
</para>
-<!-- ##### FUNCTION gdk_pixbuf_init ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gdk_pixbuf_preinit ##### -->
-<para>
-
-</para>
-
-@app:
-@modinfo:
-
-
-<!-- ##### FUNCTION gdk_pixbuf_postinit ##### -->
-<para>
-
-</para>
-
-@app:
-@modinfo:
-
-
<!-- ##### VARIABLE gdk_pixbuf_version ##### -->
<para>
<!-- ##### SECTION Title ##### -->
-refcounting
+Reference Counting and Memory Mangement
<!-- ##### SECTION Short_Description ##### -->
+Functions to perform reference counting and memory management on a
+#GdkPixbuf.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ #GdkPixbuf structures are reference counted. This means that
+ an application can share a single pixbuf among many parts of the
+ code. When a piece of the program needs to keep a pointer to a
+ pixbuf, it should add a reference to it. When it no longer needs
+ the pixbuf, it should subtract a reference. The pixbuf will be
+ destroyed when its reference count drops to zero. Newly-created
+ #GdkPixbuf structures start with a reference count of one.
+ </para>
+
+ <para>
+ <emphasis>Finalizing</emphasis> a pixbuf means to free its pixel
+ data and to free the #GdkPixbuf structure itself. Most of the
+ library functions that create #GdkPixbuf structures create the
+ pixel data by themselves and define the way it should be freed;
+ you do not need to worry about those. The only function that lets
+ you specify how to free the pixel data is
+ gdk_pixbuf_new_from_data(). Since you pass it a pre-allocated
+ pixel buffer, you must also specify a way to free that data. This
+ is done with a function of type #GdkPixbufDestroyNotify. When a
+ pixbuf created with gdk_pixbuf_new_from_data() is finalized, your
+ destroy notification function will be called, and it is its
+ responsibility to free the pixel array.
+ </para>
+
+ <para>
+ As an extension to traditional reference counting, #GdkPixbuf
+ structures support defining a handler for the last unref
+ operation. If gdk_pixbuf_unref() is called on a #GdkPixbuf
+ structure that has a reference count of 1, i.e. its last
+ reference, then the pixbuf's last unref handler function will be
+ called. It is up to this function to determine whether to
+ finalize the pixbuf using gdk_pixbuf_finalize() or to just
+ continue execution. This can be used to implement a pixbuf cache
+ efficiently; please see the programmer's documentation for
+ details.
+ </para>
+
+<!-- FIXME: link the last sentence above to the relevant section of
+ the programmer's docs.
+-->
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ #GdkPixbuf, gdk_pixbuf_new_from_data().
+ </para>
<!-- ##### USER_FUNCTION GdkPixbufDestroyNotify ##### -->
-<para>
-
-</para>
+ <para>
+ A function of this type is responsible for freeing the pixel array
+ of a pixbuf. The gdk_pixbuf_new_from_data() function lets you
+ pass in a pre-allocated pixel array so that a pixbuf can be
+ created from it; in this case you will need to pass in a function
+ of #GdkPixbufDestroyNotify so that the pixel data can be freed
+ when the pixbuf is finalized.
+ </para>
-@pixels:
-@data:
+@pixels: The pixel array of the pixbuf that is being finalized.
+@data: User closure data.
<!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
-<para>
-</para>
+ </para>
@pixbuf:
@Returns:
<!-- ##### SECTION Title ##### -->
-scaling
+Scaling
<!-- ##### SECTION Short_Description ##### -->
-
+Scaling pixbufs and scaling and compositing pixbufs
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ The &gdk-pixbuf; contains functions to scale pixbufs, to scale
+ pixbufs and composite against an existing image, and to scale
+ pixbufs and composite against a solid color or checkerboard.
+ Compositing a checkerboard is a common way to show an image with
+ an alpha channel in image-viewing and editing software.
+ </para>
+
+ <para>
+ Since the full-featured functions (gdk_pixbuf_scale(),
+ gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are
+ rather complex to use and have many arguments, two simple
+ convenience functions are provided, gdk_pixbuf_scale_simple() and
+ gdk_pixbuf_composite_color_simple() which create a new pixbuf of a
+ given size, scale an original image to fit, and then return the
+ new pixmap.
+ </para>
+
+ <para>
+ The following example demonstrates handling an expose event by
+ rendering the appropriate area of a source image (which is scaled
+ to fit the widget) onto the widget's window. The source image is
+ rendered against a checkerboard, which provides a visual
+ representation of the alpha channel if the image has one. If the
+ image doesn't have an alpha channel, calling
+ gdk_pixbuf_composite_color() function has exactly the same effect
+ as calling gdk_pixbuf_scale().
+ </para>
+
+ <programlisting>
+gboolean
+expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
+{
+ GdkPixbuf *dest;
+
+ gdk_window_set_back_pixmap (widget->window, NULL, FALSE);
+
+ dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);
+
+ gdk_pixbuf_composite_color (pixbuf, dest,
+ 0, 0, event->area.width, event->area.height,
+ -event->area.x, -event->area.y,
+ (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
+ (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
+ GDK_INTERP_BILINEAR, 255,
+ event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);
+
+ gdk_pixbuf_render_to_drawable (dest, widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
+ 0, 0, event->area.x, event->area.y,
+ event->area.width, event->area.height,
+ GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);
+
+ gdk_pixbuf_unref (dest);
+
+ return TRUE;
+}
+ </programlisting>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ GdkRGB
+ </para>
<!-- ##### ENUM GdkInterpType ##### -->
-<para>
-
-</para>
-
-@GDK_INTERP_NEAREST:
-@GDK_INTERP_TILES:
-@GDK_INTERP_BILINEAR:
-@GDK_INTERP_HYPER:
+ <para>
+ This enumeration describes the different interpolation modes that
+ can be used with the scaling functions.
+
+ <note>
+ <para>
+ Cubic filtering is missing from the list; hyperbolic
+ interpolation is just as fast and results in higher quality.
+ </para>
+ </note>
+ </para>
+
+@GDK_INTERP_NEAREST: Nearest neighbor sampling; this is the fastest
+and lowest quality mode.
+@GDK_INTERP_TILES: This is an accurate simulation of the PostScript
+image operator without any interpolation enabled. Each pixel is
+rendered as a tiny parallelogram of solid color, the edges of which
+are implemented with antialiasing. It resembles nearest neighbor for
+enlargement, and bilinear for reduction.
+@GDK_INTERP_BILINEAR: Bilinear interpolation. For enlargement, it is
+equivalent to point-sampling the ideal bilinear-interpolated image.
+For reduction, it is equivalent to laying down small tiles and
+integrating over the coverage area.
+@GDK_INTERP_HYPER: This is the slowest and highest quality
+reconstruction function. It is derived from the hyperbolic filters in
+Wolberg's "Digital Image Warping", and is formally defined as the
+hyperbolic-filter sampling the ideal hyperbolic-filter interpolated
+image (the filter is designed to be idempotent for 1:1 pixel mapping).
<!-- ##### FUNCTION gdk_pixbuf_scale ##### -->
<para>
@check_size:
@color1:
@color2:
-@Returns:
+@Returns: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
<!-- ##### SECTION Title ##### -->
-util
+Utilities
<!-- ##### SECTION Short_Description ##### -->
-
+Utility and miscellaneous convenience functions.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ These functions provide miscellaneous utilities for manipulating
+ pixbufs. The pixel data in pixbufs may of course be manipulated
+ directly by applications, but several common operations can be
+ performed by these functions instead.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ #GdkPixbuf
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_add_alpha ##### -->
<para>
@height:
@dest_pixbuf:
@dest_x:
-@dest_y:
+@dest_y: <!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
<!-- ##### FUNCTION gdk_pixbuf_saturate_and_pixelate ##### -->
# The directory containing the source code (if it contains documentation).
DOC_SOURCE_DIR=$(top_srcdir)/gdk
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS=
+
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html
+# Used for dependencies
+HFILE_GLOB=$(top_srcdir)/gdk/*.h $(top_srcdir)/gdk/x11/gdkx.h
+CFILE_GLOB=$(top_srcdir)/gdk/*.c
+
# Header files to ignore when scanning
IGNORE_HFILES= \
gdkkeysyms.h \
EXTRA_HFILES= \
$(top_srcdir)/gdk/x11/gdkx.h
-tmpl_sources = \
- tmpl/color_contexts.sgml \
- tmpl/colors.sgml \
- tmpl/cursors.sgml \
- tmpl/dnd.sgml \
- tmpl/drawing.sgml \
- tmpl/event_structs.sgml \
- tmpl/events.sgml \
- tmpl/fonts.sgml \
- tmpl/gcs.sgml \
- tmpl/gdk-unused.sgml \
- tmpl/general.sgml \
- tmpl/images.sgml \
- tmpl/input.sgml \
- tmpl/input_contexts.sgml \
- tmpl/input_devices.sgml \
- tmpl/input_methods.sgml \
- tmpl/keys.sgml \
- tmpl/pango_interaction.sgml \
- tmpl/pixbufs.sgml \
- tmpl/pixmaps.sgml \
- tmpl/properties.sgml \
- tmpl/regions.sgml \
- tmpl/rgb.sgml \
- tmpl/selections.sgml \
- tmpl/threads.sgml \
- tmpl/visuals.sgml \
- tmpl/windows.sgml \
- tmpl/x_interaction.sgml
+# Images to copy into HTML directory
+HTML_IMAGES =
# Extra SGML files that are included by DOC_MAIN_SGML_FILE
content_files =
+# Other files to distribute
+extra_files =
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed
+# if $(DOC_MODULE).types is non-empty.
+GTKDOC_CFLAGS =
+GTKDOC_LIBS =
+
+# Commands for compiling and linking
+GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
+GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
+
####################################
# Everything below here is generic #
TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
EXTRA_DIST = \
- $(DOC_MAIN_SGML_FILE) \
$(content_files) \
+ $(extra_files) \
+ $(HTML_IMAGES) \
+ $(DOC_MAIN_SGML_FILE) \
+ $(DOC_MODULE).types \
$(DOC_MODULE)-sections.txt \
$(DOC_MODULE)-overrides.txt
+DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp
+
if ENABLE_GTK_DOC
-all-local: html/index.html
+all-local: html-build.stamp
+
+SCANOBJ_FILES = \
+ $(DOC_MODULE).args \
+ $(DOC_MODULE).hierarchy \
+ $(DOC_MODULE).signal
+
+scan-build.stamp: $(HFILE_GLOB)
+ @echo '*** Scanning header files ***'
+ cd $(srcdir) && ( \
+ if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \
+ else \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
+ fi )
+ cd $(srcdir) && \
+ gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
+ touch scan-build.stamp
-$(DOC_MODULE)-decl.txt:
- $(MAKE) scan
+check_scan:
+ $(MAKE) scan-build.stamp
-$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
- $(MAKE) templates
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan
-sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt
- $(MAKE) sgml
+tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
+ @echo '*** Rebuilding template files ***'
+ cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+ touch tmpl-build.stamp
-html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE) $(content_files)
- $(MAKE) html
-endif
+check_templates:
+ $(MAKE) tmpl-build.stamp
-scan:
- -(cd $(srcdir) \
- && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(EXTRA_HFILES))
+tmpl.stamp: check_templates
-templates:
- cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+sgml-build.stamp: tmpl.stamp $(CFILE_GLOB)
+ @echo '*** Building SGML ***'
+ cd $(srcdir) && \
+ gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
+ touch sgml-build.stamp
-sgml:
- cd $(srcdir) \
- && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR)
+check_sgml:
+ $(MAKE) sgml-build.stamp
-html:
+sgml.stamp: check_sgml
+
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE)
+ @echo '*** Building HTML ***'
test -d $(srcdir)/html || mkdir $(srcdir)/html
- -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
@echo '-- Fixing Crossreferences'
cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
+ touch html-build.stamp
+endif
clean-local:
- rm -f *~ *.bak *.signals *-unused.txt
+ rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp
maintainer-clean-local: clean
cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
dist-check-gtkdoc:
else
dist-check-gtkdoc:
- @echo "*** gtk-doc must be installed and enabled in order to make dist
+ @echo "*** gtk-doc must be installed and enabled in order to make dist"
@false
endif
-dist-hook: dist-check-gtkdoc
- mkdir $(distdir)/html
- mkdir $(distdir)/sgml
+dist-hook: dist-check-gtkdoc dist-hook-local
mkdir $(distdir)/tmpl
- -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(srcdir)/html/index.sgml $(distdir)/html
+ mkdir $(distdir)/sgml
+ mkdir $(distdir)/html
-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
+ -cp $(srcdir)/html/index.sgml $(distdir)/html
+ -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
+ for i in $(HTML_IMAGES) ; do \
+ cp $(srcdir)/$$i $(distdir)/html ; \
+ done
-.PHONY : html sgml templates scan
+.PHONY : check_sgml check_templates check_scan dist-hook-local
Colormaps and Colors
<!-- ##### SECTION Short_Description ##### -->
-
+manipulation of colors and colormaps.
<!-- ##### SECTION Long_Description ##### -->
<para>
+These functions are used to modify colormaps.
+A colormap is an object that contains the mapping
+between the color values stored in memory and
+the RGB values that are used to display color
+values. In general, colormaps only contain
+significant information for pseudo-color visuals,
+but even for other visual types, a colormap object
+is required in some circumstances.
+</para>
+
+<para>
+There are a couple of special colormaps that can
+be retrieved. The system colormap (retrieved
+with gdk_colormap_get_system()) is the default
+colormap of the system. If you are using GdkRGB,
+there is another colormap that is important - the
+colormap in which GdkRGB works, retrieved with
+gdk_rgb_get_cmap(). However, when using GdkRGB,
+it is not generally necessary to allocate colors
+directly.
+</para>
+<para>
+In previous revisions of this interface, a number
+of functions that take a #GdkColormap parameter
+were replaced with functions whose names began
+with "gdk_colormap_". This process will probably
+be extended somewhat in the future -
+gdk_color_white(), gdk_color_black(), and
+gdk_color_change() will probably become aliases.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GdkColor ##### -->
<para>
-
+The #GdkColor structure is used to describe an
+allocated or unallocated color.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry><structfield>pixel</structfield></entry>
+<entry>For allocated colors, the value used to
+draw this color on the screen.</entry>
+</row>
+
+<row>
+<entry><structfield>red</structfield></entry>
+<entry>The red component of the color. This is
+a value between 0 and 65535, with 65535 indicating
+full intensitiy.</entry>
+</row>
+
+<row>
+<entry><structfield>green</structfield></entry>
+<entry>the blue component of the color.</entry>
+</row>
+
+<row>
+<entry><structfield>blue</structfield></entry>
+<entry>the green component of the color..</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@pixel:
<!-- ##### STRUCT GdkColormap ##### -->
<para>
-
+The colormap structure contains the following public
+fields.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry><structfield>size</structfield></entry>
+<entry>For pseudo-color colormaps, the number of colors
+in the colormap..</entry>
+</row>
+
+<row>
+<entry><structfield>colors</structfield></entry>
+<entry>An array containing the current values in the
+colormap. This can be used to map from pixel values
+back to RGB values. This is only meaningful for
+pseudo-color colormaps.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@parent_instance:
<!-- ##### FUNCTION gdk_colormap_new ##### -->
<para>
-
+Create a new colormap for the given visual.
</para>
-@visual:
-@allocate:
-@Returns:
+@visual: a #GdkVisual.
+@allocate: if %TRUE, the newly created colormap will be
+ a private colormap, and all colors in it will be
+ allocated for the applications use.
+@Returns: the new #GdkColormap.
<!-- ##### FUNCTION gdk_colormap_ref ##### -->
<para>
-
+Increase the reference count of a colormap.
</para>
-@cmap:
-@Returns:
+@cmap: a #GdkColormap.
+@Returns: @cmap
<!-- ##### FUNCTION gdk_colormap_unref ##### -->
<para>
-
+Decrease the reference count of a colormap. If the
+resulting reference count is zero, destroys the colormap.
</para>
-@cmap:
+@cmap: a #GdkColormap.
<!-- ##### FUNCTION gdk_colormap_get_system ##### -->
<para>
-
+Returns the system's default colormap.
</para>
-@Returns:
+@Returns: the default colormap.
<!-- ##### FUNCTION gdk_colormap_get_system_size ##### -->
<para>
-
+Returns the size of the system's default colormap.
+(See the description of struct #GdkColormap for an
+explanation of the size of a colormap.)
</para>
-@Returns:
+@Returns: the size of the system's default colormap.
<!-- ##### FUNCTION gdk_colormap_change ##### -->
<para>
-
+Change the value of the first @ncolors in a private colormap
+to match the values in the <structfield>colors</structfield>
+array in the color map. This function is obsolete and
+should not be used. See gdk_color_change().
</para>
-@colormap:
-@ncolors:
+@colormap: a #GdkColormap.
+@ncolors: the number of colors to change.
<!-- ##### FUNCTION gdk_colormap_alloc_colors ##### -->
<para>
-
+Allocates colors from a colormap.
</para>
-@colormap:
-@colors:
-@ncolors:
-@writeable:
-@best_match:
-@success:
-@Returns:
+@colormap: a #GdkColormap.
+@colors: The color values to allocate. On return, the pixel
+ values for allocated colors will be filled in.
+@ncolors: The number of colors in @colors.
+@writeable: If %TRUE, the colors are allocated writeable
+ (their values can later be changed using gdk_color_change()).
+ Writeable colors cannot be shared between applications.
+@best_match: If %TRUE, GDK will attempt to do matching against
+ existing colors if the colors cannot be allocated as
+ requested.
+@success: An array of length @ncolors. On return, this
+ indicates whether the corresponding color in @colors was
+ sucessfully allocated or not.
+@Returns: The number of colors that were not sucessfully
+ allocated.
<!-- ##### FUNCTION gdk_colormap_alloc_color ##### -->
<para>
-
+Allocate a single color from a colormap.
</para>
-@colormap:
-@color:
-@writeable:
-@best_match:
-@Returns:
+@colormap: a #GdkColormap.
+@color: the color to allocate. On return the
+<structfield>pixel</structfield> field will be
+filled in if allocation succeeds.
+@writeable: If %TRUE, the color is allocated writeable
+ (their values can later be changed using gdk_color_change()).
+ Writeable colors cannot be shared between applications.
+@best_match: If %TRUE, GDK will attempt to do matching against
+ existing colors if the color cannot be allocated as
+ requested.
+@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_colormap_free_colors ##### -->
<para>
-
+Free previously allocated colors.
</para>
-@colormap:
-@colors:
-@ncolors:
+@colormap: a #GdkColormap.
+@colors: the colors to free.
+@ncolors: the number of colors in @colors.
<!-- ##### FUNCTION gdk_colormap_get_visual ##### -->
<para>
-
+Return the visual for which a given colormap was created.
</para>
-@colormap:
-@Returns:
+@colormap: a #GdkColormap.
+@Returns: the visual of the colormap.
<!-- ##### FUNCTION gdk_colors_store ##### -->
<para>
-
+Change the value of the first @ncolors colors in
+a private colormap. This function is obsolete and
+should not be used. See gdk_color_change().
</para>
-@colormap:
-@colors:
-@ncolors:
+@colormap: a #GdkColormap.
+@colors: the new color values.
+@ncolors: the number of colors to change.
<!-- ##### FUNCTION gdk_color_copy ##### -->
<para>
-
+Make a copy of a color structure. The result
+must be freed using gdk_color_free().
</para>
-@color:
-@Returns:
+@color: a #GdkColor.
+@Returns: a copy of @color.
<!-- ##### FUNCTION gdk_color_free ##### -->
<para>
-
+Free a color structure created with
+gdk_color_copy().
</para>
-@color:
+@color: a #GdkColor.
<!-- ##### FUNCTION gdk_colors_alloc ##### -->
<para>
-
+Allocate colors from a colormap. This function
+is obsolete. See gdk_colormap_alloc_colors().
+For full documentation of the fields, see
+the Xlib documentation for XAllocColorCells.
</para>
-@colormap:
-@contiguous:
-@planes:
-@nplanes:
-@pixels:
-@npixels:
+@colormap: a #GdkColormap.
+@contiguous: if %TRUE, the colors should be allocated
+ in contiguous color cells.
+@planes: an array in which to store the plane masks.
+@nplanes: the number of planes to allocate. (Or zero,
+ to indicate that the color allocation should not be
+ planar.)
+@pixels: an array into which to store allocated pixel
+ values.
+@npixels: the number of pixels in each plane to allocate.
@Returns:
<!-- ##### FUNCTION gdk_colors_free ##### -->
<para>
-
+Free colors allocated with gdk_colors_alloc(). This
+function is obsolete. See gdk_colormap_free_colors().
</para>
-@colormap:
-@pixels:
-@npixels:
-@planes:
+@colormap: a #GdkColormap.
+@pixels: the pixel values of the colors to free.
+@npixels: the number of values in @pixels.
+@planes: the plane masks for all planes to free, OR'd
+ together.
<!-- ##### FUNCTION gdk_color_white ##### -->
<para>
-
+Return the white color for a given colormap. The resulting
+value has already allocated been allocated.
</para>
-@colormap:
-@color:
-@Returns:
+@colormap: a #GdkColormap.
+@color: the location to store the color.
+@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_color_black ##### -->
<para>
-
+Return the black color for a given colormap. The resulting
+value has already benn allocated.
</para>
-@colormap:
-@color:
-@Returns:
+@colormap: a #GdkColormap.
+@color: the location to store the color.
+@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_color_parse ##### -->
<para>
-
+Parse a textual specification of a color and fill in
+the <structfield>red</structfield>,
+<structfield>green</structfield>, and
+<structfield>blue</structfield> fields of a
+#GdkColor structure. The color is <emphasis>not</emphasis>
+allocated, you must call gdk_colormap_alloc_color() yourself.
+The text string can be in any of the forms accepted
+by <function>XParseColor</function>; these include
+name for a color from <filename>rgb.txt</filename>, such as
+<literal>DarkSlateGray</literal>, or a hex specification
+such as <literal>305050</literal>.
</para>
-@spec:
-@color:
+@spec: the string specifying the color.
+@color: the #GdkColor to fill in
@Returns:
<!-- ##### FUNCTION gdk_color_alloc ##### -->
<para>
-
+Allocate a single color from a colormap.
+This function is obsolete. See gdk_colormap_alloc_color().
</para>
-@colormap:
-@color:
-@Returns:
+@colormap: a #GdkColormap.
+@color: The color to allocate. On return, the
+<structfield>pixel</structfield> field will be
+filled in.
+@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_color_change ##### -->
<para>
-
+Change the value of a color that has already
+been allocated. If @colormap is not a private
+colormap, then the color must have been allocated
+using gdk_colormap_alloc_colors() with the
+@writeable set to %TRUE.
</para>
-@colormap:
-@color:
+@colormap: a #GdkColormap.
+@color: a #GdkColor, with the color to change
+in the <structfield>pixel</structfield> field,
+and the new value in the remaining fields.
@Returns:
<!-- ##### FUNCTION gdk_color_equal ##### -->
<para>
-
+Compare two colors.
</para>
-@colora:
-@colorb:
-@Returns:
+@colora: a #GdkColor.
+@colorb: another #GdkColor.
+@Returns: %TRUE if the two colors compare equal
<!-- ##### FUNCTION gdk_color_hash ##### -->
<para>
-
+A hash function suitable for using for a hash
+table that stores #GdkColor's.
</para>
-@colora:
-@Returns:
+@colora: a #GdkColor.
+@Returns: The hash function appled to @colora
+<!-- # Unused Parameters # -->
+@colorb: NOT USED.
Drawing Primitives
<!-- ##### SECTION Short_Description ##### -->
-
+functions for drawing points, lines, arcs, and text.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These functions provide support for drawing points, lines, arcs and text
+onto what are called 'drawables'. Drawables, as the name suggests, are things
+which support drawing onto them, and are either #GdkWindow or #GdkPixmap
+objects.
+</para>
+<para>
+Many of the drawing operations take a #GdkGC argument, which represents a
+graphics context. This #GdkGC contains a number of drawing attributes such
+as foreground color, background color and line width, and is used to reduce
+the number of arguments needed for each drawing operation. See the
+<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
+more information.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### FUNCTION gdk_draw_point ##### -->
<para>
-
+Draws a point, using the foreground color and other attributes of the #GdkGC.
</para>
-@drawable:
-@gc:
-@x:
-@y:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@x: the x coordinate of the point.
+@y: the y coordinate of the point.
<!-- ##### FUNCTION gdk_draw_points ##### -->
<para>
-
+Draws a number of points, using the foreground color and other attributes of
+the #GdkGC.
</para>
-@drawable:
-@gc:
-@points:
-@npoints:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@points: an array of #GdkPoint structures.
+@npoints: the number of points to be drawn.
<!-- ##### FUNCTION gdk_draw_line ##### -->
<para>
-
+Draws a line, using the foreground color and other attributes of the #GdkGC.
</para>
-@drawable:
-@gc:
-@x1:
-@y1:
-@x2:
-@y2:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@x1: the x coordinate of the start point.
+@y1: the y coordinate of the start point.
+@x2: the x coordinate of the end point.
+@y2: the y coordinate of the end point.
<!-- ##### FUNCTION gdk_draw_lines ##### -->
<para>
-
+Draws a series of lines connecting the given points.
+The way in which joins between lines are draw is determined by the
+#GdkCapStyle value in the #GdkGC. This can be set with
+gdk_gc_set_line_attributes().
</para>
-@drawable:
-@gc:
-@points:
-@npoints:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@points: an array of #GdkPoint structures specifying the endpoints of the
+lines.
+@npoints: the size of the @points array.
<!-- ##### FUNCTION gdk_draw_segments ##### -->
<para>
-
+Draws a number of unconnected lines.
</para>
-@drawable:
-@gc:
-@segs:
-@nsegs:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@segs: an array of #GdkSegment structures specifying the start and end points
+of the lines to be drawn,
+@nsegs: the number of line segments to draw, i.e. the size of the @segs array.
<!-- ##### STRUCT GdkSegment ##### -->
<para>
-
+Specifies the start and end point of a line for use by the gdk_draw_segments()
+function.
</para>
-@x1:
-@y1:
-@x2:
-@y2:
+@x1: the x coordinate of the start point.
+@y1: the y coordinate of the start point.
+@x2: the x coordinate of the end point.
+@y2: the y coordinate of the end point.
<!-- ##### FUNCTION gdk_draw_rectangle ##### -->
<para>
-
+Draws a rectangular outline or filled rectangle, using the foreground color
+and other attributes of the #GdkGC.
</para>
+<note>
+<para>
+A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle
+outlined. Calling gdk_draw_rectangle (window, gc, TRUE, 0, 0, 20, 20) results
+in a filled rectangle 20 pixels wide and 20 pixels high. Calling
+gdk_draw_rectangle (window, gc, FALSE, 0, 0, 20, 20) results in an outlined
+rectangle with corners at (0, 0), (0, 20), (20, 20), and (20, 0), which
+makes it 21 pixels wide and 21 pixels high.
+</para>
+</note>
-@drawable:
-@gc:
-@filled:
-@x:
-@y:
-@width:
-@height:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@filled: TRUE if the rectangle should be filled.
+@x: the x coordinate of the left edge of the rectangle.
+@y: the y coordinate of the top edge of the rectangle.
+@width: the width of the rectangle.
+@height: the height of the rectangle.
<!-- ##### FUNCTION gdk_draw_arc ##### -->
<para>
-
+Draws an arc or a filled 'pie slice'. The arc is defined by the bounding
+rectangle of the entire ellipse, and the start and end angles of the part of
+the ellipse to be drawn.
</para>
-@drawable:
-@gc:
-@filled:
-@x:
-@y:
-@width:
-@height:
-@angle1:
-@angle2:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@filled: TRUE if the arc should be filled, producing a 'pie slice'.
+@x: the x coordinate of the left edge of the bounding rectangle.
+@y: the y coordinate of the top edge of the bounding rectangle.
+@width: the width of the bounding rectangle.
+@height: the height of the bounding rectangle.
+@angle1: the start angle of the arc, relative to the 3 o'clock position,
+counter-clockwise, in 1/64ths of a degree.
+@angle2: the end angle of the arc, relative to @angle1, in 1/64ths of a degree.
<!-- ##### FUNCTION gdk_draw_polygon ##### -->
<para>
-
+Draws an outlined or filled polygon.
</para>
-@drawable:
-@gc:
-@filled:
-@points:
-@npoints:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@filled: TRUE if the polygon should be filled. The polygon is closed
+automatically, connecting the last point to the first point if necessary.
+@points: an array of #GdkPoint structures specifying the points making up the
+polygon.
+@npoints: the number of points.
<!-- ##### FUNCTION gdk_draw_glyphs ##### -->
<!-- ##### FUNCTION gdk_draw_string ##### -->
<para>
-
+Draws a string of characters in the given font or fontset.
</para>
-@drawable:
-@font:
-@gc:
-@x:
-@y:
-@string:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@font: a #GdkFont.
+@gc: a #GdkGC.
+@x: the x coordinate of the left edge of the text.
+@y: the y coordinate of the baseline of the text.
+@string: the string of characters to draw.
<!-- ##### FUNCTION gdk_draw_text ##### -->
<para>
-
+Draws a number of characters in the given font or fontset.
</para>
-@drawable:
-@font:
-@gc:
-@x:
-@y:
-@text:
-@text_length:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@font: a #GdkFont.
+@gc: a #GdkGC.
+@x: the x coordinate of the left edge of the text.
+@y: the y coordinate of the baseline of the text.
+@text: the characters to draw.
+@text_length: the number of characters of @text to draw.
<!-- ##### FUNCTION gdk_draw_text_wc ##### -->
<para>
-
+Draws a number of wide characters using the given font of fontset.
+If the font is a 1-byte font, the string is converted into 1-byte characters
+(discarding the high bytes) before output.
</para>
-@drawable:
-@font:
-@gc:
-@x:
-@y:
-@text:
-@text_length:
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@font: a #GdkFont.
+@gc: a #GdkGC.
+@x: the x coordinate of the left edge of the text.
+@y: the y coordinate of the baseline of the text.
+@text: the wide characters to draw.
+@text_length: the number of characters to draw.
<!-- ##### MACRO gdk_draw_pixmap ##### -->
<para>
-
+Draws a pixmap, or a part of a pixmap, onto another drawable.
</para>
+<!-- # Unused Parameters # -->
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@src: the source #GdkPixmap to draw.
+@xsrc: the left edge of the source rectangle within @src.
+@ysrc: the top of the source rectangle within @src.
+@xdest: the x coordinate of the destination within @drawable.
+@ydest: the y coordinate of the destination within @drawable.
+@width: the width of the area to be copied, or -1 to make the area extend to
+the right edge of the source pixmap.
+@height: the height of the area to be copied, or -1 to make the area extend
+to the bottom edge of the source pixmap.
<!-- ##### FUNCTION gdk_draw_drawable ##### -->
<!-- ##### FUNCTION gdk_draw_image ##### -->
<para>
-
-</para>
-
-@drawable:
-@gc:
-@image:
-@xsrc:
-@ysrc:
-@xdest:
-@ydest:
-@width:
-@height:
+Draws a #GdkImage onto a drawable.
+The depth of the #GdkImage must match the depth of the #GdkDrawable.
+</para>
+
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@image: the #GdkImage to draw.
+@xsrc: the left edge of the source rectangle within @image.
+@ysrc: the top of the source rectangle within @image.
+@xdest: the x coordinate of the destination within @drawable.
+@ydest: the y coordinate of the destination within @drawable.
+@width: the width of the area to be copied, or -1 to make the area extend to
+the right edge of @image.
+@height: the height of the area to be copied, or -1 to make the area extend
+to the bottom edge of @image.
<!-- ##### FUNCTION gdk_drawable_get_image ##### -->
Fonts
<!-- ##### SECTION Short_Description ##### -->
-
+loading and manipulating fonts
<!-- ##### SECTION Long_Description ##### -->
<para>
+The GdkFont data type represents a font for drawing on
+the screen. These functions provide support for
+loading fonts, and also for determining the dimensions
+of characters and strings when drawn with a particular
+font.
+</para>
+<para>
+Fonts in X are specified by a
+<firstterm>X Logical Font Description</firstterm>.
+The following description is considerably simplified.
+For definitive information about XLFD's see the
+X reference documentation. A X Logical Font Description (XLFD)
+consists of a sequence of fields separated (and surrounded by) '-'
+characters. For example, Adobe Helvetica Bold 12 pt, has the
+full description:
+
+<programlisting>
+"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"
+</programlisting>
+</para>
+
+<para>
+The fields in the XLFD are:
+
+<informaltable pgwide=1 frame="none">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>Foundry</entry>
+<entry>the company or organization where the font originated.</entry>
+</row>
+
+<row>
+<entry>Family</entry>
+<entry>the font family (a group of related font designs).</entry>
+</row>
+
+<row>
+<entry>Weight</entry>
+<entry>A name for the font's typographic weight
+For example, 'bold' or 'medium').</entry>
+</row>
+
+<row>
+<entry>Slant</entry>
+<entry>The slant of the font. Common values are 'R' for Roman,
+'I' for italoc, and 'O' for oblique.</entry>
+</row>
+
+<row>
+<entry>Set Width</entry>
+<entry>A name for the width of the font. For example,
+'normal' or 'condensed'.</entry>
+</row>
+
+<row>
+<entry>Add Style</entry>
+<entry>Additional information to distinguish a font from
+other fonts of the same family.</entry>
+</row>
+
+<row>
+<entry>Pixel Size</entry>
+<entry>The body size of the font in pixels.</entry>
+</row>
+
+<row>
+<entry>Point Size</entry>
+<entry>The body size of the font in 10ths of a point.
+(A <firstterm>point</firstterm> is 1/72.27 inch) </entry>
+</row>
+
+<row>
+<entry>Resolution X</entry>
+<entry>The horizontal resolution that the font was designed for.</entry>
+</row>
+
+<row>
+<entry>Resolution Y</entry>
+<entry>The vertical resolution that the font was designed for .</entry>
+</row>
+
+<row>
+<entry>Spacing</entry>
+<entry>The type of spacing for the font - can be 'p' for proportional,
+'m' for monospaced or 'c' for charcell.</entry>
+</row>
+
+<row>
+<entry>Average Width</entry>
+<entry>The average width of a glyph in the font. For monospaced
+and charcell fonts, all glyphs in the font have this width</entry>
+</row>
+
+<row>
+<entry>Charset Registry</entry>
+<entry>The registration authority that owns the encoding for
+the font. Together with the Charset Encoding field, this
+defines the character set for the font.</entry>
+</row>
+
+<row>
+<entry>Charset Encoding</entry>
+<entry>An identifier for the particular character set encoding.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+<para>
+When specifying a font via a X logical Font Description,
+'*' can be used as a wildcard to match any portion of
+the XLFD. For instance, the above example could
+also be specified as
+
+<programlisting>
+"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"
+</programlisting>
+
+It is generally a good idea to use wildcards for any
+portion of the XLFD that your program does not care
+about specifically, since that will improve the
+chances of finding a matching font.
+</para>
+
+<para>
+A <firstterm>fontset</firstterm> is a list of fonts
+that is used for drawing international text that may
+contain characters from a number of different character
+sets. It is represented by a list of XLFD's.
+</para>
+
+<para>
+The font for a given character set is determined by going
+through the list of XLFD's in order. For each one, if
+the registry and and encoding fields match the desired
+character set, then that font is used, otherwise if
+the XLFD contains wild-cards for the registry and encoding
+fields, the registry and encoding for the desired character
+set are subsituted in and a lookup is done. If a match is found
+that font is used. Otherwise, processing continues
+on to the next font in the list.
+</para>
+
+<para>
+The functions for determining the metrics of a string
+come in several varieties that can take a number
+of forms of string input:
+
+<variablelist>
+ <varlistentry>
+ <term>8-bit string</term>
+ <listitem><para>
+ When using functions like gdk_string_width() that
+ take a <type>gchar *</type>, if the font is of type
+ %GDK_FONT_FONT and is an 8-bit font, then each
+ <type>gchar</type> indexes the glyphs in the font directly.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>16-bit string</term>
+ <listitem><para>
+ For functions taking a <type>gchar *</type>, if the
+ font is of type %GDK_FONT_FONT, and is a 16-bit
+ font, then the <type>gchar *</type> argument is
+ interpreted as a <type>guint16 *</type> cast to
+ a <type>gchar *</type> and each <type>guint16</type>
+ indexes the glyphs in the font directly.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Multibyte string</term>
+ <listitem><para>
+ For functions taking a <type>gchar *</type>, if the
+ font is of type %GDK_FONT_FONTSET, then the input
+ string is interpreted as a <firstterm>multibyte</firstterm>
+ encoded according to the current locale. (A multibyte
+ string is one in which each character may consist
+ of one or more bytes, with different lengths for different
+ characters in the string). They can be converted to and
+ from wide character strings (see below) using
+ gdk_wcstombs() and gdk_mbstowcs().) The string will
+ be rendered using one or more different fonts from
+ the fontset.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Wide character string</term>
+ <listitem><para>
+ For a number of the text-measuring functions, GTK+
+ provides a variant (such as gdk_text_width_wc()) which
+ takes a <type>GdkWChar *</type> instead of a
+ <type>gchar *</type>. The input is then taken to
+ be a wide character string in the encoding of the
+ current locale. (A wide character string is a string
+ in which each character consists of several bytes,
+ and the width of each character in the string is
+ constant.)
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+<para>
+GDK provides functions to determine a number of different
+measurements (metrics) for a given string. (Need diagram
+here).
+
+<variablelist>
+ <varlistentry>
+ <term>ascent</term>
+ <listitem><para>
+ The vertical distance from the origin of the drawing
+ opereration to the top of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>descent</term>
+ <listitem><para>
+ The vertical distance from the origin of the drawing
+ opereration to the bottom of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>left bearing</term>
+ <listitem><para>
+ The horizontal distance from the origin of the drawing
+ operation to the left-most part of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>right bearing</term>
+ <listitem><para>
+ The horizontal distance from the origin of the drawing
+ operation to the right-most part of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>width bearing</term>
+ <listitem><para>
+ The horizontal distance from the origin of the drawing
+ operation to the correct origin for drawing another
+ string to follow the current one. Depending on the
+ font, this could be greater than or less than the
+ right bearing.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GdkFont ##### -->
<para>
-
+The GdkFont structure represents a font or fontset. It
+contains the following public fields. A new GdkFont
+structure is returned by gdk_font_load() or gdk_fontset_load(),
+and is reference counted with gdk_font_ref() and gdk_font_unref()
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry><structfield>type</structfield></entry>
+<entry>a value of type #GdkFontType which indicates
+whether this font is a single font or a fontset.</entry>
+</row>
+
+<row>
+<entry><structfield>ascent</structfield></entry>
+<entry>the maximum distance that the font, when drawn,
+ascends above the baseline.</entry>
+</row>
+
+<row>
+<entry><structfield>descent</structfield></entry>
+<entry>the maximum distance that the font, when drawn,
+descends below the baseline.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@type:
<!-- ##### ENUM GdkFontType ##### -->
<para>
+Indicates the type of a font. The possible values
+are currently:
+
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GDK_FONT_FONT</entry>
+<entry>the font is a single font.</entry>
+</row>
+
+<row>
+<entry>GDK_FONT_FONT</entry>
+<entry>the font is a fontset.</entry>
+</row>
+</tbody></tgroup></informaltable>
</para>
@GDK_FONT_FONT:
<!-- ##### FUNCTION gdk_font_load ##### -->
<para>
+Loads a font.
+</para>
+<para>
+Currently, this function will always return a new
+font, however, in the future, it may be changed to
+look up the font in a cache. You should make no
+assumptions about the initial reference count.
</para>
-@font_name:
-@Returns:
+@font_name: a XLFD describing the font to load.
+@Returns: a #GdkFont, or NULL if the font could not be loaded.
<!-- ##### FUNCTION gdk_fontset_load ##### -->
<para>
-
+Loads a fontset.
+</para>
+<para>
+Currently this function will always return a new
+font, however, in the future, it may be changed to
+look up the font in a cache. You should make no
+assumptions about the initial reference count.
</para>
-@fontset_name:
-@Returns:
+@fontset_name: a comma-separated list of XLFDs describing
+ the component fonts of the fontset to load.
+@Returns: a #GdkFont, or NULL if the fontset could not be loaded.
<!-- ##### FUNCTION gdk_font_from_description ##### -->
<!-- ##### FUNCTION gdk_font_ref ##### -->
<para>
-
+Increase the reference count of a count by one.
</para>
-@font:
-@Returns:
+@font: a #GdkFont
+@Returns: @font
<!-- ##### FUNCTION gdk_font_unref ##### -->
<para>
-
+Decrease the reference count of a count by one.
+If the result is zero, destroys the font.
</para>
-@font:
+@font: a #GdkFont
<!-- ##### FUNCTION gdk_font_id ##### -->
<para>
-
+Returns the X Font ID for the given font.
</para>
-@font:
-@Returns:
+@font: a #GdkFont.
+@Returns: the numeric X Font ID
<!-- ##### FUNCTION gdk_font_equal ##### -->
<para>
-
+Compares two fonts for equality. Single fonts compare equal
+if they have the same X font ID. This operation does
+not currently work correctly for fontsets.
</para>
-@fonta:
-@fontb:
-@Returns:
+@fonta: a #GdkFont.
+@fontb: another #GdkFont.
+@Returns: %TRUE if the fonts are equal.
<!-- ##### FUNCTION gdk_string_extents ##### -->
<para>
-
+Returns the metrics of a NULL-terminated string.
</para>
-@font:
-@string:
-@lbearing:
-@rbearing:
-@width:
-@ascent:
-@descent:
+@font: a #GdkFont.
+@string: the NULL-terminated string to measure.
+@lbearing: the left bearing of the string.
+@rbearing: the right bearing of the string.
+@width: the width of the string.
+@ascent: the ascent of the string.
+@descent: the descent of the string.
<!-- ##### FUNCTION gdk_text_extents ##### -->
<para>
-
+Returns the metrics of a string.
</para>
-@font:
-@text:
-@text_length:
-@lbearing:
-@rbearing:
-@width:
-@ascent:
-@descent:
+@font: a #GdkFont
+@text: the text to measure
+@text_length: the length of the text in bytes. (If the
+ font is a 16-bit font, this is twice the length
+ of the text in characters.)
+@lbearing: the left bearing of the string.
+@rbearing: the right bearing of the string.
+@width: the width of the string.
+@ascent: the ascent of the string.
+@descent: the descent of the string.
<!-- ##### FUNCTION gdk_text_extents_wc ##### -->
<para>
-
+Returns the metrics of a string of wide characters.
</para>
-@font:
-@text:
-@text_length:
-@lbearing:
-@rbearing:
-@width:
-@ascent:
-@descent:
+@font: a #GdkFont
+@text: the text to measure.
+@text_length: the length of the text in character.
+@lbearing: the left bearing of the string.
+@rbearing: the right bearing of the string.
+@width: the width of the string.
+@ascent: the ascent of the string.
+@descent: the descent of the string.
<!-- ##### FUNCTION gdk_string_width ##### -->
<para>
-
+Determine the width of a NULL-terminated string.
+(The distance from the origin of the string to the
+point where the next string in a sequence of strings
+should be drawn)
</para>
-@font:
-@string:
-@Returns:
+@font: a #GdkFont
+@string: the NULL-terminated string to measure
+@Returns: the width of the string in pixels.
<!-- ##### FUNCTION gdk_text_width ##### -->
<para>
-
+Determine the width of a given string.
</para>
-@font:
-@text:
-@text_length:
-@Returns:
+@font: a #GdkFont
+@text: the text to measure.
+@text_length: the length of the text in bytes.
+@Returns: the width of the string in pixels.
<!-- ##### FUNCTION gdk_text_width_wc ##### -->
<para>
-
+Determine the width of a given wide-character string.
</para>
-@font:
-@text:
-@text_length:
-@Returns:
+@font: a #GdkFont
+@text: the text to measure.
+@text_length: the length of the text in characters.
+@Returns: the width of the string in pixels.
<!-- ##### FUNCTION gdk_char_width ##### -->
<para>
-
+Determine the width of a given character.
</para>
-@font:
-@character:
-@Returns:
+@font: a #GdkFont
+@character: the character to measure.
+@Returns: the width of the character in pixels.
<!-- ##### FUNCTION gdk_char_width_wc ##### -->
<para>
-
+Determine the width of a given wide character. (Encoded
+in the wide-character encoding of the current locale).
</para>
-@font:
-@character:
-@Returns:
+@font: a #GdkFont
+@character: the character to measure.
+@Returns: the width of the character in pixels.
<!-- ##### FUNCTION gdk_string_measure ##### -->
<para>
-
+Determines the distance from the origin to the rightmost
+portion of a NULL-terminated string when drawn. This is not the
+correct value for determining the origin of the next
+portion when drawing text in multiple pieces.
+See gdk_string_width().
</para>
-@font:
-@string:
-@Returns:
+@font: a #GdkFont
+@string: the NULL-terminated string to measure.
+@Returns: the right bearing of the string in pixels.
<!-- ##### FUNCTION gdk_text_measure ##### -->
<para>
-
+Determines the distance from the origin to the rightmost
+portion of a string when drawn. This is not the
+correct value for determining the origin of the next
+portion when drawing text in multiple pieces.
+See gdk_text_width().
</para>
-@font:
-@text:
-@text_length:
-@Returns:
+@font: a #GdkFont
+@text: the text to measure.
+@text_length: the length of the text in bytes.
+@Returns: the right bearing of the string in pixels.
<!-- ##### FUNCTION gdk_char_measure ##### -->
<para>
-
+Determines the distance from the origin to the rightmost
+portion of a character when drawn. This is not the
+correct value for determining the origin of the next
+portion when drawing text in multiple pieces.
</para>
-@font:
-@character:
-@Returns:
+@font: a #GdkFont
+@character: the character to measure.
+@Returns: the right bearing of the character in pixels.
<!-- ##### FUNCTION gdk_string_height ##### -->
<para>
-
+Determines the total height of a given NULL-terminated
+string. This value is not generally useful, because you
+cannot determine how this total height will be drawn in
+relation to the baseline. See gdk_string_extents().
</para>
-@font:
-@string:
-@Returns:
+@font: a #GdkFont
+@string: the NULL-terminated string to measure.
+@Returns: the height of the string in pixels.
<!-- ##### FUNCTION gdk_text_height ##### -->
<para>
-
+Determines the total height of a given string.
+This value is not generally useful, because you cannot
+determine how this total height will be drawn in
+relation to the baseline. See gdk_text_extents().
</para>
-@font:
-@text:
-@text_length:
-@Returns:
+@font: a #GdkFont
+@text: the text to measure.
+@text_length: the length of the text in bytes.
+@Returns: the height of the string in pixels.
<!-- ##### FUNCTION gdk_char_height ##### -->
<para>
-
+Determines the total height of a given character.
+This value is not generally useful, because you cannot
+determine how this total height will be drawn in
+relation to the baseline. See gdk_text_extents().
</para>
-@font:
-@character:
-@Returns:
+@font: a #GdkFont
+@character: the character to measure.
+@Returns: the height of the character in pixels.
<!-- ##### FUNCTION gdk_font_full_name_get ##### -->
<!-- ##### TYPEDEF GdkWChar ##### -->
<para>
-
+Specifies a wide character type, used to represent character codes.
+This is needed since some native languages have character sets which have
+more than 256 characters (Japanese and Chinese, for example).
+</para>
+<para>
+Wide character values between 0 and 127 are always identical in meaning to
+the ASCII character codes. The wide character value 0 is often used to
+terminate strings of wide characters in a similar way to normal strings
+using the char type.
+</para>
+<para>
+An alternative to wide characters is multi-byte characters, which extend
+normal char strings to cope with larger character sets. As the name suggests,
+multi-byte characters use a different number of bytes to store different
+character codes. For example codes 0-127 (i.e. the ASCII codes) often
+use just one byte of memory, while other codes may use 2, 3 or even 4 bytes.
+Multi-byte characters have the advantage that they can often be used in an
+application with little change, since strings are still represented as arrays
+of char values. However multi-byte strings are much easier to manipulate since
+the character are all of the same size.
+</para>
+<para>
+Applications typically use wide characters to represent character codes
+internally, and multi-byte strings when saving the characters to a file.
+The gdk_wcstombs() and gdk_mbstowcs() functions can be used to convert from
+one representation to the other.
+</para>
+<para>
+See the 'Extended Characters' section of the GNU C Library Reference Manual
+for more detailed information on wide and multi-byte characters.
</para>
<!-- ##### FUNCTION gdk_wcstombs ##### -->
<para>
-
+Converts a wide character string to a multi-byte string.
+(The function name comes from an acronym of 'Wide Character String TO
+Multi-Byte String').
</para>
-@src:
-@Returns:
+@src: a wide character string.
+@Returns: the multi-byte string corresponding to @src, or NULL if the
+conversion failed. The returned string should be freed with g_free() when no
+longer needed.
<!-- ##### FUNCTION gdk_mbstowcs ##### -->
<para>
-
+Converts a multi-byte string to a wide character string.
+(The function name comes from an acronym of 'Multi-Byte String TO Wide
+Character String').
</para>
-@dest:
-@src:
-@dest_max:
-@Returns:
+@dest: the space to place the converted wide character string into.
+@src: the multi-byte string to convert, which must be null-terminated.
+@dest_max: the maximum number of wide characters to place in @dest.
+@Returns: the number of wide characters written into @dest, or -1 if the
+conversion failed.
Graphics Contexts
<!-- ##### SECTION Short_Description ##### -->
-
+objects to encapsulate drawing properties.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+All drawing operations in GDK take a
+<firstterm>graphics context</firstterm> (GC) argument.
+A graphics context encapsulates information about
+the way things are drawn, such as the foreground
+color or line width. By using graphics contexts,
+the number of arguments to each drawing call is
+greatly reduced, and communication overhead is
+minimized, since identical arguments do not need
+to be passed repeatedly.
+</para>
+<para>
+Most values of a graphics context can be set at
+creation time by using gdk_gc_new_with_values(),
+or can be set one-by-one using functions such
+as gdk_gc_set_foreground(). A few of the values
+in the GC, such as the dash pattern, can only
+be set by the latter method.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GdkGC ##### -->
<para>
-
+The #GdkGC structure represents a graphics context.
+It is an opaque structure with no user-visible
+elements.
</para>
@parent_instance:
<!-- ##### STRUCT GdkGCValues ##### -->
<para>
-
+The #GdkGCValues structure holds a set of values used
+to create or modify a graphics context.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#GdkColor foreground;</entry>
+<entry>the foreground color.</entry>
+</row>
+
+<row>
+<entry>#GdkColor background;</entry>
+<entry>the background color.</entry>
+</row>
+
+<row>
+<entry>#GdkFont *font;</entry>
+<entry>the default font..</entry>
+</row>
+
+<row>
+<entry>#GdkFunction function;</entry>
+<entry>the bitwise operation used when drawing.</entry>
+</row>
+
+<row>
+<entry>#GdkFill fill;</entry>
+<entry>the fill style.</entry>
+</row>
+
+<row>
+<entry>#GdkPixmap *tile;</entry>
+<entry>the tile pixmap.</entry>
+</row>
+
+<row>
+<entry>#GdkPixmap *stipple;</entry>
+<entry>the stipple bitmap.</entry>
+</row>
+
+<row>
+<entry>#GdkPixmap *clip_mask;</entry>
+<entry>the clip mask bitmap.</entry>
+</row>
+
+<row>
+<entry>#GdkSubwindowMode subwindow_mode;</entry>
+<entry>the subwindow mode.</entry>
+</row>
+
+<row>
+<entry>#gint ts_x_origin;</entry>
+<entry>the x origin of the tile or stipple.</entry>
+</row>
+
+<row>
+<entry>#gint ts_y_origin;</entry>
+<entry>the y origin of the tile or stipple.</entry>
+</row>
+
+<row>
+<entry>#gint clip_x_origin;</entry>
+<entry>the x origin of the clip mask.</entry>
+</row>
+
+<row>
+<entry>#gint clip_y_origin;</entry>
+<entry>the y origin of the clip mask.</entry>
+</row>
+
+<row>
+<entry>#gint graphics_exposures;</entry>
+<entry>whether graphics exposures are enabled.</entry>
+</row>
+
+<row>
+<entry>#gint line_width;</entry>
+<entry>the line width</entry>
+</row>
+
+<row>
+<entry>#GdkLineStyle line_style;</entry>
+<entry>the way dashed lines are drawn</entry>
+</row>
+
+<row>
+<entry>#GdkCapStyle cap_style;</entry>
+<entry>the way the ends of lines are drawn</entry>
+</row>
+
+<row>
+<entry>#GdkJoinStyle join_style;</entry>
+<entry>the way joins between lines are drawn</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@foreground:
<!-- ##### ENUM GdkGCValuesMask ##### -->
<para>
-
+A set of bit flags used to indicate which fields
+#GdkGCValues structure are set.
</para>
@GDK_GC_FOREGROUND:
<!-- ##### ENUM GdkFunction ##### -->
<para>
-
+Determines how the bit values for the source pixels are combined with
+the bit values for destination pixels to produce the final result. The
+sixteen values here correspond to the 16 different possible 2x2 truth
+tables. Only a couple of these values are usually useful; for colored
+images, only %GDK_COPY, %GDK_XOR and %GDK_INVERT are generally
+useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
</para>
@GDK_COPY:
<!-- ##### FUNCTION gdk_gc_new ##### -->
<para>
-
+Create a new graphics context with default values.
</para>
@drawable:
-@Returns:
+@Returns: the new graphics context.
+<!-- # Unused Parameters # -->
+@window: a #GdkDrawable. The created GC must always be used
+ with drawables of the same depth as this one.
<!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
<para>
-
+Create a new GC with the given initial values.
</para>
@drawable:
-@values:
-@values_mask:
-@Returns:
+@values: a structure containing initial values for the GC.
+@values_mask: a bit mask indicating which fields in @values
+ are set.
+@Returns: the new graphics context.
+<!-- # Unused Parameters # -->
+@window: a #GdkDrawable. The created GC must always be used
+ with drawables of the same depth as this one.
<!-- ##### FUNCTION gdk_gc_ref ##### -->
<para>
-
+Increase the reference count on a graphics context.
</para>
-@gc:
-@Returns:
+@gc: a #GdkGC.
+@Returns: @gc.
<!-- ##### FUNCTION gdk_gc_unref ##### -->
<para>
-
+Decrease the reference count on a graphics context. If
+the resulting reference count is zero, the graphics
+context will be destroyed.
</para>
-@gc:
+@gc: a #GdkGC.
<!-- ##### MACRO gdk_gc_destroy ##### -->
<para>
-
+Identical to gdk_gc_unref(). This function is obsolete
+and should not be used.
</para>
+<!-- # Unused Parameters # -->
+@gc: a #GdkGC.
<!-- ##### FUNCTION gdk_gc_set_values ##### -->
<!-- ##### FUNCTION gdk_gc_get_values ##### -->
<para>
-
+Retrieves the current values from a graphics context.
</para>
-@gc:
-@values:
+@gc: a #GdkGC.
+@values: the #GdkGCValues structure in which to store the results.
<!-- ##### FUNCTION gdk_gc_set_foreground ##### -->
<para>
-
+Sets the foreground color for a graphics context.
</para>
-@gc:
-@color:
+@gc: a #GdkGC.
+@color: the new foreground color.
<!-- ##### FUNCTION gdk_gc_set_background ##### -->
<para>
-
+Sets the background color for a graphics context.
</para>
-@gc:
-@color:
+@gc: a #GdkGC.
+@color: the new background color.
<!-- ##### FUNCTION gdk_gc_set_rgb_fg_color ##### -->
<!-- ##### FUNCTION gdk_gc_set_font ##### -->
<para>
-
+Sets the font for a graphics context. (Note that
+all text-drawing functions in GDK take a @font
+argument; the value set here is used when that
+argument is %NULL.)
</para>
-@gc:
-@font:
+@gc: a #GdkGC.
+@font: the new font.
<!-- ##### FUNCTION gdk_gc_set_function ##### -->
<para>
-
+Determines how the current pixel values and the
+pixel values being drawn are combined to produce
+the final pixel values.
</para>
-@gc:
+@gc: a #GdkGC.
@function:
<!-- ##### FUNCTION gdk_gc_set_fill ##### -->
<para>
-
+Set the fill mode for a graphics context.
</para>
-@gc:
-@fill:
+@gc: a #GdkGC.
+@fill: the new fill mode.
<!-- ##### ENUM GdkFill ##### -->
<para>
+Determines how primitives are drawn.
+
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+<row>
+<entry>GDK_SOLID</entry>
+<entry>draw with the foreground color.</entry>
+</row>
+
+<row>
+<entry>GDK_TILED</entry>
+<entry>draw with a tiled pixmap.</entry>
+</row>
+
+<row>
+<entry>GDK_STIPPLED</entry>
+<entry>draw using the stipple bitmap. Pixels corresponding
+to bits in the stipple bitmap that are set will be drawn in the
+foreground color; pixels corresponding to bits that are
+not set will be left untouched.</entry>
+</row>
+
+<row>
+<entry>GDK_OPAQUE_STIPPLED</entry>
+<entry>draw using the stipple bitmap. Pixels corresponding
+to bits in the stipple bitmap that are set will be drawn in the
+foreground color; pixels corresponding to bits that are
+not set will be drawn with the background color.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@GDK_SOLID:
<!-- ##### FUNCTION gdk_gc_set_tile ##### -->
<para>
-
+Set a tile pixmap for a graphics context.
+This will only be used if the fill mode
+is %GDK_TILED.
</para>
-@gc:
-@tile:
+@gc: a #GdkGC.
+@tile: the new tile pixmap.
<!-- ##### FUNCTION gdk_gc_set_stipple ##### -->
<para>
-
+Set the stipple bitmap for a graphics context. The
+stipple will only be used if the fill mode is
+%GDK_STIPPLED or %GDK_OPAQUE_STIPPLED.
</para>
-@gc:
-@stipple:
+@gc: a #GdkGC.
+@stipple: the new stipple bitmap.
<!-- ##### FUNCTION gdk_gc_set_ts_origin ##### -->
<para>
-
+Set the origin when using tiles or stipples with
+the GC. The tile or stipple will be aligned such
+that the upper left corner of the tile or stipple
+will coincide with this point.
</para>
-@gc:
-@x:
-@y:
+@gc: a #GdkGC.
+@x: the x-coordinate of the origin.
+@y: the y-coordinate of the origin.
<!-- ##### FUNCTION gdk_gc_set_clip_origin ##### -->
<para>
-
+Sets the origin of the clip mask. The coordinates are
+interpreted relative to the upper-left corner of
+the destination drawable of the current operation.
</para>
-@gc:
-@x:
-@y:
+@gc: a #GdkGC.
+@x: the x-coordinate of the origin.
+@y: the y-coordinate of the origin.
<!-- ##### FUNCTION gdk_gc_set_clip_mask ##### -->
<para>
-
+Sets the clip mask for a graphics context from a bitmap.
+The clip mask is interpreted relative to the clip
+origin. (See gdk_gc_set_clip_origin()).
</para>
-@gc:
-@mask:
+@gc: the #GdkGC.
+@mask: a bitmap.
<!-- ##### FUNCTION gdk_gc_set_clip_rectangle ##### -->
<para>
+Sets the clip mask for a graphics context from a
+rectangle. The clip mask is interpreted relative to the clip
+origin. (See gdk_gc_set_clip_origin()).
</para>
-@gc:
-@rectangle:
+@gc: a #GdkGC.
+@rectangle: the rectangle to clip to.
<!-- ##### FUNCTION gdk_gc_set_clip_region ##### -->
<para>
-
+Sets the clip mask for a graphics context from a region structure.
+The clip mask is interpreted relative to the clip origin. (See
+gdk_gc_set_clip_origin()).
</para>
-@gc:
-@region:
+@gc: a #GdkGC.
+@region: the #GdkRegion.
<!-- ##### FUNCTION gdk_gc_set_subwindow ##### -->
<para>
-
+Sets how drawing with this GC on a window will affect child
+windows of that window.
</para>
-@gc:
-@mode:
+@gc: a #GdkGC.
+@mode: the subwindow mode.
<!-- ##### ENUM GdkSubwindowMode ##### -->
<para>
+Determines how drawing onto a window will affect child
+windows of that window.
+
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="3*"><colspec colwidth="7*">
+<tbody>
+
+<row>
+<entry>GDK_CLIP_BY_CHILDREN</entry>
+<entry>only draw onto the window itself.</entry>
+</row>
+
+<row>
+<entry>GDK_INCLUDE_INFERIORS</entry>
+<entry>Draw onto the window and child windows.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@GDK_CLIP_BY_CHILDREN:
<!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
<para>
-
+Sets whether copying non-visible portions of a drawable
+using this graphics context generate exposure events
+for the corresponding regions of the destination
+drawable. (See gdk_draw_pixmap()).
</para>
-@gc:
-@exposures:
+@gc: a #GdkGC.
+@exposures: if %TRUE, exposure events will be generated.
<!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
<para>
-
+Sets various attributes of how lines are drawn. See
+the corresponding members of GdkGCValues for full
+explanations of the arguments.
</para>
-@gc:
-@line_width:
-@line_style:
-@cap_style:
-@join_style:
+@gc: a #GdkGC.
+@line_width: the width of lines.
+@line_style: the dash-style for lines.
+@cap_style: the manner in which the ends of lines are drawn.
+@join_style: the in which lines are joined together.
<!-- ##### ENUM GdkLineStyle ##### -->
<para>
+Determines how lines are drawn.
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GDK_LINE_SOLID</entry>
+<entry>lines are drawn solid.</entry>
+</row>
+
+<row>
+<entry>GDK_LINE_ON_OFF_DASH</entry>
+<entry>even segments are drawn; odd segments are not drawn.</entry>
+</row>
+
+<row>
+<entry>GDK_LINE_DOUBLE_DASH</entry>
+<entry>even segments are normally. Odd segments are drawn
+in the background color if the fill style is %GDK_SOLID,
+or in the background color masked by the stipple if the
+fill style is %GDK_STIPPLED.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@GDK_LINE_SOLID:
<!-- ##### ENUM GdkCapStyle ##### -->
<para>
+Determines how the end of lines are drawn.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+<row>
+<entry>GDK_CAP_NOT_LAST</entry>
+<entry>the same as %GDK_CAP_BUTT for lines of non-zero width.
+ for zero width lines, the final point on the line
+ will not be drawn.</entry>
+</row>
+
+<row>
+<entry>GDK_CAP_BUTT</entry>
+<entry>the ends of the lines are drawn squared off and extending
+ to the coordinates of the end point.</entry>
+</row>
+
+<row>
+<entry>GDK_CAP_ROUND</entry>
+<entry>the ends of the lines are drawn as semicircles with the
+ diameter equal to the line width and centered at the
+ end point.</entry>
+</row>
+
+<row>
+<entry>GDK_CAP_PROJECTING</entry>
+<entry>the ends of the lines are drawn squared off and extending
+ half the width of the line beyond the end point.</entry>
+</row>
+</tbody></tgroup></informaltable>
</para>
@GDK_CAP_NOT_LAST:
<!-- ##### ENUM GdkJoinStyle ##### -->
<para>
+Determines how the joins between segments of a polygon are drawn.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GDK_JOIN_MITER</entry>
+<entry>the sides of each line are extended to meet at an angle.</entry>
+</row>
+<row>
+<entry>GDK_JOIN_ROUND</entry>
+<entry>the sides of the two lines are joined by a circular arc.</entry>
+</row>
+
+<row>
+<entry>GDK_JOIN_BEVEL</entry>
+<entry>the sides of the two lines are joined by a straight line which
+ makes an equal angle with each line.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@GDK_JOIN_MITER:
<!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
<para>
-
+Sets the way dashed-lines are drawn. Lines will be
+drawn with alternating on and off segments of the
+lengths specified in @dash_list. The manner in
+which the on and off segments are drawn is determined
+by the @line_style value of the GC. (This can
+be changed with gdk_gc_set_line_attributes)
</para>
-@gc:
-@dash_offset:
-@dash_list:
-@n:
+@gc: a #GdkGC.
+@dash_offset: the
+@dash_list: an array of dash lengths.
+@n: the number of elements in @dash_list.
<!-- ##### FUNCTION gdk_gc_copy ##### -->
<para>
-
+Copy the set of values from one graphics context
+onto another graphics context.
</para>
-@dst_gc:
-@src_gc:
+@dst_gc: the destination graphics context.
+@src_gc: the source graphics context.
<!-- ##### FUNCTION gdk_gc_set_colormap ##### -->
+<!-- ##### SECTION ./tmpl/color_contexts.sgml:Long_Description ##### -->
+<para>
+The #GdkColorContext type is used for allocating groups of colors.
+</para>
+<para>
+It is now deprecated in favor of the gdk_colormap_*() functions described in
+the <link linkend="gdk-Colormaps-and-Colors">Colormaps and Colors</link>
+section.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/color_contexts.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/color_contexts.sgml:Short_Description ##### -->
+routines for allocating colors (deprecated).
+
+
+<!-- ##### SECTION ./tmpl/color_contexts.sgml:Title ##### -->
+Color Contexts
+
+
+<!-- ##### SECTION ./tmpl/colors.sgml:Long_Description ##### -->
+<para>
+These functions are used to modify colormaps.
+A colormap is an object that contains the mapping
+between the color values stored in memory and
+the RGB values that are used to display color
+values. In general, colormaps only contain
+significant information for pseudo-color visuals,
+but even for other visual types, a colormap object
+is required in some circumstances.
+</para>
+
+<para>
+There are a couple of special colormaps that can
+be retrieved. The system colormap (retrieved
+with gdk_colormap_get_system()) is the default
+colormap of the system. If you are using GdkRGB,
+there is another colormap that is important - the
+colormap in which GdkRGB works, retrieved with
+gdk_rgb_get_cmap(). However, when using GdkRGB,
+it is not generally necessary to allocate colors
+directly.
+</para>
+
+<para>
+In previous revisions of this interface, a number
+of functions that take a #GdkColormap parameter
+were replaced with functions whose names began
+with "gdk_colormap_". This process will probably
+be extended somewhat in the future -
+gdk_color_white(), gdk_color_black(), and
+gdk_color_change() will probably become aliases.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/colors.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/colors.sgml:Short_Description ##### -->
+manipulation of colors and colormaps.
+
+
+<!-- ##### SECTION ./tmpl/colors.sgml:Title ##### -->
+Colormaps and Colors
+
+
+<!-- ##### SECTION ./tmpl/cursors.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/cursors.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/cursors.sgml:Short_Description ##### -->
+standard and pixmap cursors.
+
+
+<!-- ##### SECTION ./tmpl/cursors.sgml:Title ##### -->
+Cursors
+
+
+<!-- ##### SECTION ./tmpl/dnd.sgml:Long_Description ##### -->
+<para>
+These functions provide a low level interface for drag and drop.
+GDK supports both the Xdnd and Motif drag and drop protocols transparently.
+</para>
+<para>
+GTK+ provides a higher level abstraction based on top of these functions,
+and so they are not normally needed in GTK+ applications.
+See the <link linkend="gtk-Drag-and-Drop">Drag and Drop</link> section of
+the GTK+ documentation for more information.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dnd.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dnd.sgml:Short_Description ##### -->
+functions for controlling drag and drop handling.
+
+
+<!-- ##### SECTION ./tmpl/dnd.sgml:Title ##### -->
+Drag and Drop
+
+
+<!-- ##### SECTION ./tmpl/drawing.sgml:Long_Description ##### -->
+<para>
+These functions provide support for drawing points, lines, arcs and text
+onto what are called 'drawables'. Drawables, as the name suggests, are things
+which support drawing onto them, and are either #GdkWindow or #GdkPixmap
+objects.
+</para>
+<para>
+Many of the drawing operations take a #GdkGC argument, which represents a
+graphics context. This #GdkGC contains a number of drawing attributes such
+as foreground color, background color and line width, and is used to reduce
+the number of arguments needed for each drawing operation. See the
+<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
+more information.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/drawing.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/drawing.sgml:Short_Description ##### -->
+functions for drawing points, lines, arcs, and text.
+
+
+<!-- ##### SECTION ./tmpl/drawing.sgml:Title ##### -->
+Drawing Primitives
+
+
+<!-- ##### SECTION ./tmpl/event_structs.sgml:Long_Description ##### -->
+<para>
+The event structs contain data specific to each type of event in GDK.
+</para>
+<note>
+<para>
+A common mistake is to forget to set the event mask of a widget so that the
+required events are received. See gtk_widget_set_events().
+</para>
+</note>
+
+
+<!-- ##### SECTION ./tmpl/event_structs.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/event_structs.sgml:Short_Description ##### -->
+data structures specific to each type of event.
+
+
+<!-- ##### SECTION ./tmpl/event_structs.sgml:Title ##### -->
+Event Structures
+
+
+<!-- ##### SECTION ./tmpl/events.sgml:Long_Description ##### -->
+<para>
+This section describes functions dealing with events from the window system.
+</para>
+<para>
+In GTK+ applications the events are handled automatically in
+gtk_main_do_event() and passed on to the appropriate widgets, so these
+functions are rarely needed. Though some of the fields in the
+<link linkend="gdk-Event-Structures">Event Structures</link> are useful.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/events.sgml:See_Also ##### -->
+<para>
+<variablelist>
+<varlistentry>
+<term><link linkend="gdk-Event-Structures">Event Structures</link></term>
+<listitem><para>
+The structs used for each type of event.
+</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+
+<!-- ##### SECTION ./tmpl/events.sgml:Short_Description ##### -->
+functions for handling events from the window system.
+
+
+<!-- ##### SECTION ./tmpl/events.sgml:Title ##### -->
+Events
+
+
+<!-- ##### SECTION ./tmpl/fonts.sgml:Long_Description ##### -->
+<para>
+The GdkFont data type represents a font for drawing on
+the screen. These functions provide support for
+loading fonts, and also for determining the dimensions
+of characters and strings when drawn with a particular
+font.
+</para>
+
+<para>
+Fonts in X are specified by a
+<firstterm>X Logical Font Description</firstterm>.
+The following description is considerably simplified.
+For definitive information about XLFD's see the
+X reference documentation. A X Logical Font Description (XLFD)
+consists of a sequence of fields separated (and surrounded by) '-'
+characters. For example, Adobe Helvetica Bold 12 pt, has the
+full description:
+
+<programlisting>
+"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"
+</programlisting>
+</para>
+
+<para>
+The fields in the XLFD are:
+
+<informaltable pgwide=1 frame="none">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>Foundry</entry>
+<entry>the company or organization where the font originated.</entry>
+</row>
+
+<row>
+<entry>Family</entry>
+<entry>the font family (a group of related font designs).</entry>
+</row>
+
+<row>
+<entry>Weight</entry>
+<entry>A name for the font's typographic weight
+For example, 'bold' or 'medium').</entry>
+</row>
+
+<row>
+<entry>Slant</entry>
+<entry>The slant of the font. Common values are 'R' for Roman,
+'I' for italoc, and 'O' for oblique.</entry>
+</row>
+
+<row>
+<entry>Set Width</entry>
+<entry>A name for the width of the font. For example,
+'normal' or 'condensed'.</entry>
+</row>
+
+<row>
+<entry>Add Style</entry>
+<entry>Additional information to distinguish a font from
+other fonts of the same family.</entry>
+</row>
+
+<row>
+<entry>Pixel Size</entry>
+<entry>The body size of the font in pixels.</entry>
+</row>
+
+<row>
+<entry>Point Size</entry>
+<entry>The body size of the font in 10ths of a point.
+(A <firstterm>point</firstterm> is 1/72.27 inch) </entry>
+</row>
+
+<row>
+<entry>Resolution X</entry>
+<entry>The horizontal resolution that the font was designed for.</entry>
+</row>
+
+<row>
+<entry>Resolution Y</entry>
+<entry>The vertical resolution that the font was designed for .</entry>
+</row>
+
+<row>
+<entry>Spacing</entry>
+<entry>The type of spacing for the font - can be 'p' for proportional,
+'m' for monospaced or 'c' for charcell.</entry>
+</row>
+
+<row>
+<entry>Average Width</entry>
+<entry>The average width of a glyph in the font. For monospaced
+and charcell fonts, all glyphs in the font have this width</entry>
+</row>
+
+<row>
+<entry>Charset Registry</entry>
+<entry>The registration authority that owns the encoding for
+the font. Together with the Charset Encoding field, this
+defines the character set for the font.</entry>
+</row>
+
+<row>
+<entry>Charset Encoding</entry>
+<entry>An identifier for the particular character set encoding.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+<para>
+When specifying a font via a X logical Font Description,
+'*' can be used as a wildcard to match any portion of
+the XLFD. For instance, the above example could
+also be specified as
+
+<programlisting>
+"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"
+</programlisting>
+
+It is generally a good idea to use wildcards for any
+portion of the XLFD that your program does not care
+about specifically, since that will improve the
+chances of finding a matching font.
+</para>
+
+<para>
+A <firstterm>fontset</firstterm> is a list of fonts
+that is used for drawing international text that may
+contain characters from a number of different character
+sets. It is represented by a list of XLFD's.
+</para>
+
+<para>
+The font for a given character set is determined by going
+through the list of XLFD's in order. For each one, if
+the registry and and encoding fields match the desired
+character set, then that font is used, otherwise if
+the XLFD contains wild-cards for the registry and encoding
+fields, the registry and encoding for the desired character
+set are subsituted in and a lookup is done. If a match is found
+that font is used. Otherwise, processing continues
+on to the next font in the list.
+</para>
+
+<para>
+The functions for determining the metrics of a string
+come in several varieties that can take a number
+of forms of string input:
+
+<variablelist>
+ <varlistentry>
+ <term>8-bit string</term>
+ <listitem><para>
+ When using functions like gdk_string_width() that
+ take a <type>gchar *</type>, if the font is of type
+ %GDK_FONT_FONT and is an 8-bit font, then each
+ <type>gchar</type> indexes the glyphs in the font directly.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>16-bit string</term>
+ <listitem><para>
+ For functions taking a <type>gchar *</type>, if the
+ font is of type %GDK_FONT_FONT, and is a 16-bit
+ font, then the <type>gchar *</type> argument is
+ interpreted as a <type>guint16 *</type> cast to
+ a <type>gchar *</type> and each <type>guint16</type>
+ indexes the glyphs in the font directly.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Multibyte string</term>
+ <listitem><para>
+ For functions taking a <type>gchar *</type>, if the
+ font is of type %GDK_FONT_FONTSET, then the input
+ string is interpreted as a <firstterm>multibyte</firstterm>
+ encoded according to the current locale. (A multibyte
+ string is one in which each character may consist
+ of one or more bytes, with different lengths for different
+ characters in the string). They can be converted to and
+ from wide character strings (see below) using
+ gdk_wcstombs() and gdk_mbstowcs().) The string will
+ be rendered using one or more different fonts from
+ the fontset.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Wide character string</term>
+ <listitem><para>
+ For a number of the text-measuring functions, GTK+
+ provides a variant (such as gdk_text_width_wc()) which
+ takes a <type>GdkWChar *</type> instead of a
+ <type>gchar *</type>. The input is then taken to
+ be a wide character string in the encoding of the
+ current locale. (A wide character string is a string
+ in which each character consists of several bytes,
+ and the width of each character in the string is
+ constant.)
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+<para>
+GDK provides functions to determine a number of different
+measurements (metrics) for a given string. (Need diagram
+here).
+
+<variablelist>
+ <varlistentry>
+ <term>ascent</term>
+ <listitem><para>
+ The vertical distance from the origin of the drawing
+ opereration to the top of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>descent</term>
+ <listitem><para>
+ The vertical distance from the origin of the drawing
+ opereration to the bottom of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>left bearing</term>
+ <listitem><para>
+ The horizontal distance from the origin of the drawing
+ operation to the left-most part of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>right bearing</term>
+ <listitem><para>
+ The horizontal distance from the origin of the drawing
+ operation to the right-most part of the drawn character.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>width bearing</term>
+ <listitem><para>
+ The horizontal distance from the origin of the drawing
+ operation to the correct origin for drawing another
+ string to follow the current one. Depending on the
+ font, this could be greater than or less than the
+ right bearing.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+
+<!-- ##### SECTION ./tmpl/fonts.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/fonts.sgml:Short_Description ##### -->
+loading and manipulating fonts
+
+
+<!-- ##### SECTION ./tmpl/fonts.sgml:Title ##### -->
+Fonts
+
+
+<!-- ##### SECTION ./tmpl/gcs.sgml:Long_Description ##### -->
+<para>
+All drawing operations in GDK take a
+<firstterm>graphics context</firstterm> (GC) argument.
+A graphics context encapsulates information about
+the way things are drawn, such as the foreground
+color or line width. By using graphics contexts,
+the number of arguments to each drawing call is
+greatly reduced, and communication overhead is
+minimized, since identical arguments do not need
+to be passed repeatedly.
+</para>
+<para>
+Most values of a graphics context can be set at
+creation time by using gdk_gc_new_with_values(),
+or can be set one-by-one using functions such
+as gdk_gc_set_foreground(). A few of the values
+in the GC, such as the dash pattern, can only
+be set by the latter method.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gcs.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gcs.sgml:Short_Description ##### -->
+objects to encapsulate drawing properties.
+
+
+<!-- ##### SECTION ./tmpl/gcs.sgml:Title ##### -->
+Graphics Contexts
+
+
+<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gdkkeys.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Title ##### -->
+Keyboard Handling
+
+
+<!-- ##### SECTION ./tmpl/gdkregion.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
<!-- ##### SECTION ./tmpl/gdkregion.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### FUNCTION gdk_regions_xor ##### -->
+<!-- ##### SECTION ./tmpl/gdkregion.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gdkregion.sgml:Title ##### -->
+Points, Rectangles and Regions
+
+
+<!-- ##### SECTION ./tmpl/input.sgml:Long_Description ##### -->
+<para>
+The functions in this section are used to establish
+callbacks when some condition becomes true for
+a file descriptor. They are currently just wrappers around
+the <link linkend="glib-IO-Channels">IO Channel</link>
+facility.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input.sgml:See_Also ##### -->
+<para>
+<variablelist>
+
+<varlistentry>
+<term><link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link></term>
+<listitem><para>The main loop in which input callbacks run.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><link linkend="glib-IO-Channels">IO Channels</link></term>
+<listitem><para>A newer and more flexible way of doing IO
+callbacks.</para></listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input.sgml:Short_Description ##### -->
+Callbacks on file descriptors.
+
+
+<!-- ##### SECTION ./tmpl/input.sgml:Title ##### -->
+Input
+
+
+<!-- ##### SECTION ./tmpl/input_contexts.sgml:Long_Description ##### -->
+<para>
+A #GdkIC input context is used for each user interface element which supports
+internationalized text input. See the
+<link linkend="gdk-Input-Methods">Input Methods</link> section for an overview
+of how internationalized text input works in GTK+.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_contexts.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_contexts.sgml:Short_Description ##### -->
+internationalized text input properties.
+
+
+<!-- ##### SECTION ./tmpl/input_contexts.sgml:Title ##### -->
+Input Contexts
+
+
+<!-- ##### SECTION ./tmpl/input_devices.sgml:Long_Description ##### -->
+<para>
+In addition to the normal keyboard and mouse input devices, GTK+ also
+contains support for <firstterm>extended input devices</firstterm>. In
+particular, this support is targeted at graphics tablets. Graphics
+tablets typically return sub-pixel positioning information and possibly
+information about the pressure and tilt of the stylus. Under
+X, the support for extended devices is done through the
+<firstterm>XInput</firstterm> extension.
+</para>
+<para>
+Because handling extended input devices may involve considerable
+overhead, they need to be turned on for each #GdkWindow
+individually using gdk_input_set_extension_events().
+(Or, more typically, for GtkWidgets, using gtk_widget_set_extension_events()).
+As an additional complication, depending on the support from
+the windowing system, its possible that a normal mouse
+cursor will not be displayed for a particular extension
+device. If an application does not want to deal with displaying
+a cursor itself, it can ask only to get extension events
+from devices that will display a cursor, by passing the
+%GDK_EXTENSION_EVENTS_CURSOR value to
+gdk_input_set_extension_events(). Otherwise, the application
+must retrieve the device information using gdk_input_list_devices(),
+check the <structfield>has_cursor</structfield> field, and,
+if it is %FALSE, draw a cursor itself when it receives
+motion events.
+</para>
+<para>
+Each pointing device is assigned a unique integer ID; events from a
+particular device can be identified by the
+<structfield>deviceid</structfield> field in the event structure. The
+events generated by pointer devices have also been extended to contain
+<structfield>pressure</structfield>, <structfield>xtilt</structfield>
+and <structfield>ytilt</structfield> fields which contain the extended
+information reported as additional <firstterm>valuators</firstterm>
+from the device. The <structfield>pressure</structfield> field is a
+a double value ranging from 0.0 to 1.0, while the tilt fields are
+double values ranging from -1.0 to 1.0. (With -1.0 representing the
+maximum title to the left or up, and 1.0 representing the maximum
+tilt to the right or down.)
+</para>
+<para>
+One additional field in each event is the
+<structfield>source</structfield> field, which contains an
+enumeration value describing the type of device; this currently
+can be one of
+%GDK_SOURCE_MOUSE,
+ %GDK_SOURCE_PEN,
+%GDK_SOURCE_ERASER,
+or %GDK_SOURCE_CURSOR. This field is present to allow simple
+applications to (for instance) delete when they detect eraser
+devices without having to keep track of complicated per-device
+settings.
+</para>
+<para>
+Various aspects of each device may be configured. The easiest way of
+creating a GUI to allow the user to conifigure such a device
+is to use to use the #GtkInputDialog widget in GTK+.
+However, even when using this widget, application writers
+will need to directly query and set the configuration parameters
+in order to save the state between invocations of the application.
+The configuration of devices is queried using gdk_input_list_devices.
+Each device must is activated using gdk_input_set_mode(), which
+also controls whether the device's range is mapped to the
+entire screen or to a single window. The mapping of the valuators of
+the device onto the predefined valuator types is set using
+gdk_input_set_axes. And the source type for each device
+can be set with gdk_input_set_source().
+</para>
+<para>
+Devices may also have associated <firstterm>keys</firstterm>
+or macro buttons. Such keys can be globally set to map
+into normal X keyboard events. The mapping is set using
+gdk_input_set_key().
+</para>
+<para>
+The interfaces in this section will most likely be considerably
+modified in the future to accomodate devices that may have different
+sets of additional valuators than the pressure xtilt and ytilt.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_devices.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_devices.sgml:Short_Description ##### -->
+Functions for handling extended input devices.
+
+
+<!-- ##### SECTION ./tmpl/input_devices.sgml:Title ##### -->
+Input Devices
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Title ##### -->
+Pango Interaction
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml:Long_Description ##### -->
+<para>
+Input Methods provide a way for complex character sets to be used in GTK+.
+Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK)
+use a large number of ideographs, making it impossible to support all
+characters with a simple keyboard. Instead, text is usually
+<emphasis>pre-edited</emphasis> using a phonetic alphabet and then
+<emphasis>composed</emphasis> to form the ideographs.
+</para>
+<para>
+GTK+ makes use of the input method mechanism provided by the X Windows
+platform. When a GTK+ application is started, it opens a connection to the
+input method appropriate for the current locale (if any).
+</para>
+<para>
+Widgets which handle textual input, such as #GtkEntry, need to do a number of
+things to support internationalized text input:
+<variablelist>
+<varlistentry>
+<term>When the widget is realized:</term>
+<listitem><para>Check if an input method is being used with gdk_im_ready().
+If it is, create a new <link linkend="gdk-Input-Contexts">Input Context</link>
+using gdk_ic_new(). Find out which events the
+<link linkend="gdk-Input-Contexts">Input Context</link> needs to receive
+with gdk_ic_get_events(), and make sure that the widget's window receives
+these events using gdk_window_set_events().
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the widget's size, state or cursor position changes:</term>
+<listitem><para>
+Update the appropriate
+<link linkend="gdk-Input-Contexts">Input Context</link> attributes
+using gdk_ic_set_attr().
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the keyboard focus enters or leaves the widget:</term>
+<listitem><para>
+Call gdk_im_begin() or gdk_im_end() to start or finish editing the text.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the widget receives a key_press event:</term>
+<listitem><para>
+The <structfield>string</structfield> and <structfield>length</structfield>
+fields of the #GdkEventKey struct should be used to insert the composed text
+into the widget.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the widget is unrealized:</term>
+<listitem><para>
+Destroy the <link linkend="gdk-Input-Contexts">Input Context</link>.
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+</para>
+<para>
+See the XLib reference manual for more detailed information on input methods,
+and the #GtkEntry and #GtkText widgets for some example code.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml:See_Also ##### -->
+<para>
+<variablelist>
+<varlistentry>
+<term><link linkend="gdk-Input-Contexts">Input Contexts</link></term>
+<listitem><para>
+Used for each widget that handles internationalized text input using the
+global input method.
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml:Short_Description ##### -->
+support for internationalized text input.
+
+
+<!-- ##### SECTION ./tmpl/input_methods.sgml:Title ##### -->
+Input Methods
+
+
+<!-- ##### SECTION ./tmpl/keys.sgml:Long_Description ##### -->
+<para>
+Key values are the codes which are sent whenever a key is pressed or released.
+They appear in the <structfield>keyval</structfield> field of the
+#GdkEventKey structure, which is passed to signal handlers for the
+"key-press-event" and "key-release-event" signals.
+The complete list of key values can be found in the <gdk/gdkkeysyms.h>
+header file.
+</para>
+<para>
+Key values can be converted into a string representation using
+gdk_keyval_name(). The reverse function, converting a string to a key value,
+is provided by gdk_keyval_from_name().
+</para>
+<para>
+The case of key values can be determined using gdk_keyval_is_upper() and
+gdk_keyval_is_lower(). Key values can be converted to upper or lower case
+using gdk_keyval_to_upper() and gdk_keyval_to_lower().
+</para>
+
+
+<!-- ##### SECTION ./tmpl/keys.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/keys.sgml:Short_Description ##### -->
+functions for manipulating keyboard codes.
+
+
+<!-- ##### SECTION ./tmpl/keys.sgml:Title ##### -->
+Key Values
+
+
+<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/pango_interaction.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Title ##### -->
+Pango Interaction
+
+
+<!-- ##### SECTION ./tmpl/pixbufs.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/pixbufs.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/pixbufs.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/pixbufs.sgml:Title ##### -->
+Pixbufs
+
+
+<!-- ##### SECTION ./tmpl/properties.sgml:Long_Description ##### -->
+<para>
+Each window under X can have any number of associated
+<firstterm>properties</firstterm> attached to it.
+Properties are arbitrary chunks of data identified by
+<firstterm>atom</firstterm>s. (An <firstterm>atom</firstterm>
+is a numeric index into a string table on the X server. They are used
+to transfer strings efficiently between clients without
+having to transfer the entire string.) A property
+has an associated type, which is also identified
+using an atom.
+</para>
+<para>
+A property has an associated <firstterm>format</firstterm>,
+an integer describing how many bits are in each unit
+of data inside the property. It must be 8, 16, or 32.
+When data is transfered between the server and client,
+if they are of different endianesses it will be byteswapped
+as necessary according to the format of the property.
+Note that on the client side, properties of format 32
+will be stored with one unit per <emphasis>long</emphasis>,
+even if a long integer has more than 32 bits on the platform.
+(This decision was apparently made for Xlib to maintain
+compatibility with programs that assumed longs were 32
+bits, at the expense of programs that knew better.)
+</para>
+<para>
+The functions in this section are used to add, remove
+and change properties on windows, to convert atoms
+to and from strings and to manipulate some types of
+data commonly stored in X window properties.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/properties.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/properties.sgml:Short_Description ##### -->
+functions to manipulate properties on windows.
+
+
+<!-- ##### SECTION ./tmpl/properties.sgml:Title ##### -->
+Properties and Atoms
+
+
+<!-- ##### SECTION ./tmpl/regions.sgml:Long_Description ##### -->
+<para>
+GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types
+for representing pixels and sets of pixels on the screen.
+</para>
+<para>
+#GdkPoint is a simple structure containing an x and y coordinate of a point.
+</para>
+<para>
+#GdkRectangle is a structure holding the position and size of a rectangle.
+The intersection of two rectangles can be computed with
+gdk_rectangle_intersect(). To find the union of two rectangles use
+gdk_rectangle_union().
+</para>
+<para>
+#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
+usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
+</para>
+<para>
+#GdkSpan is a structure holding a spanline. A spanline is a horizontal line that
+is one pixel wide. It is mainly used when rasterizing other graphics primitives.
+It can be intersected to regions by using gdk_region_spans_intersect_foreach().
+</para>
+
+
+<!-- ##### SECTION ./tmpl/regions.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/regions.sgml:Short_Description ##### -->
+simple graphical data types.
+
+
+<!-- ##### SECTION ./tmpl/regions.sgml:Title ##### -->
+Points, Rectangles and Regions
+
+
+<!-- ##### SECTION ./tmpl/regions2.sgml:Long_Description ##### -->
+<para>
+GDK provides the #GdkPoint, #GdkRectangle and #GdkRegion data types for
+representing pixels and sets of pixels on the screen.
+</para>
+<para>
+#GdkPoint is a simple structure containing an x and y coordinate of a point.
+</para>
+<para>
+#GdkRectangle is a structure holding the position and size of a rectangle.
+The intersection of two rectangles can be computed with
+gdk_rectangle_intersect(). To find the union of two rectangles use
+gdk_rectangle_union().
+</para>
+<para>
+#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
+usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
+</para>
+
+
+<!-- ##### SECTION ./tmpl/regions2.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/regions2.sgml:Short_Description ##### -->
+simple graphical data types.
+
+
+<!-- ##### SECTION ./tmpl/regions2.sgml:Title ##### -->
+Points, Rectangles and Regions
+
+
+<!-- ##### SECTION ./tmpl/rgb.sgml:Long_Description ##### -->
+<para>
+
+GdkRgb converts RGB, grayscale, and colormapped images into the native
+window pixel format and displays them. It takes care of colormaps,
+visuals, dithering, and management of the temporary buffers.
+
+</para>
+
+<para>
+You must call gdk_rgb_init() before using any GdkRgb functionality. If
+you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
+(including #GtkPreview) call gdk_rgb_init() in their class_init method.
+Thus, if you use GdkRgb only indirectly, you don't need to worry
+about it.
+</para>
+
+<para>
+GdkRgb tries to use the system default visual and colormap, but
+doesn't always succeed. Thus, you have to be prepared to install the
+visual and colormap generated by GdkRgb. The following code sequence
+(before any widgets are created) should work in most applications:
+</para>
+
+<informalexample>
+<programlisting>
+ gdk_rgb_init ();
+
+ gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
+ gtk_widget_set_default_visual (gdk_rgb_get_visual ());
+</programlisting>
+</informalexample>
+
+<para>
+You can also push the colormap and visual, but in general it doesn't
+work unless the push wraps the window creation call. If you wrap the
+push around a widget which is embedded in a window without the GdkRgb
+colormap and visual, it probably won't work, and is likely to cause
+colormap flashing, as well.
+</para>
+
+<para>
+On 8-bit systems, the colormaps used by Imlib and GdkRgb may
+conflict. There is no good general solution to this other than phasing
+out the dependence on Imlib.
+</para>
+
+<para>
+You can set the threshold for installing colormaps with
+gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
+of this size or larger can be allocated in the default colormap, then
+that's done. Otherwise, GdkRgb creates its own private colormap.
+Setting it to 0 means that it always tries to use the default
+colormap, and setting it to 216 means that it always creates a private
+one if it cannot allocate the 6x6x6 colormap in the default. If you
+always want a private colormap (to avoid consuming too many colormap
+entries for other apps, say), you can use gdk_rgb_set_install(TRUE).
+Setting the value greater than 216 exercises a bug in older versions
+of GdkRgb. Note, however, that setting it to 0 doesn't let you get
+away with ignoring the colormap and visual - a colormap is always
+created in grayscale and direct color modes, and the visual is changed
+in cases where a "better" visual than the default is available.
+</para>
+
+<example>
+<title>A simple example program using GdkRGB.</title>
+<programlisting>
+#include <gtk/gtk.h>
+
+#define IMAGE_WIDTH 256
+#define IMAGE_HEIGHT 256
+
+guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
+
+gboolean on_darea_expose (GtkWidget *widget,
+ GdkEventExpose *event,
+ gpointer user_data);
+
+int
+main (int argc, char *argv[])
+{
+ GtkWidget *window, *darea;
+ gint x, y;
+ guchar *pos;
+
+ gtk_init (&argc, &argv);
+ gdk_rgb_init ();
+ window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+ darea = gtk_drawing_area_new ();
+ gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
+ gtk_container_add (GTK_CONTAINER (window), darea);
+ gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
+ GTK_SIGNAL_FUNC (on_darea_expose), NULL);
+ gtk_widget_show_all (window);
+
+ /* Set up the RGB buffer. */
+ pos = rgbbuf;
+ for (y = 0; y < IMAGE_HEIGHT; y++)
+ {
+ for (x = 0; x < IMAGE_WIDTH; x++)
+ {
+ *pos++ = x - x % 32; /* Red. */
+ *pos++ = (x / 32) * 4 + y - y % 32; /* Green. */
+ *pos++ = y - y % 32; /* Blue. */
+ }
+ }
+
+ gtk_main ();
+ return 0;
+}
+
+
+gboolean
+on_darea_expose (GtkWidget *widget,
+ GdkEventExpose *event,
+ gpointer user_data)
+{
+ gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
+ 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
+ GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
+}
+</programlisting>
+</example>
+
+
+<!-- ##### SECTION ./tmpl/rgb.sgml:See_Also ##### -->
+<para>
+<variablelist>
+
+<varlistentry>
+<term>#GdkColor</term>
+<listitem><para>The underlying Gdk mechanism for allocating
+colors.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/rgb.sgml:Short_Description ##### -->
+displays RGB images (as well as grayscale and colormapped) to
+the native window.
+
+
+<!-- ##### SECTION ./tmpl/rgb.sgml:Title ##### -->
+GdkRGB
+
+
+<!-- ##### SECTION ./tmpl/selections.sgml:Long_Description ##### -->
+<para>
+The X selection mechanism provides a way to transfer
+arbitrary chunks of data between programs.
+A <firstterm>selection</firstterm> is a essentially
+a named clipboard, identified by a string interned
+as a #GdkAtom. By claiming ownership of a selection,
+an application indicates that it will be responsible
+for supplying its contents. The most common
+selections are <literal>PRIMARY</literal> and
+<literal>CLIPBOARD</literal>.
+</para>
+<para>
+The contents of a selection can be represented in
+a number of formats, called <firstterm>targets</firstterm>.
+Each target is identified by an atom. A list of
+all possible targets supported by the selection owner
+can be retrieved by requesting the special target
+<literal>TARGETS</literal>. When a selection is
+retrieved, the data is accompanied by a type
+(an atom), and a format (an integer, representing
+the number of bits per item).
+See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
+for more information.
+</para>
+<para>
+The functions in this section only contain the lowlevel
+parts of the selection protocol. A considerably more
+complicated implementation is needed on top of this.
+GTK+ contains such an implementation in the functions
+in <literal>gtkselection.h</literal> and programmers
+should use those functions instead of the ones presented
+here. If you plan to implement selection handling
+directly on top of the functions here, you should refer
+to the X Inter-client Communication Conventions Manual
+(ICCCM).
+</para>
+
+
+<!-- ##### SECTION ./tmpl/selections.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/selections.sgml:Short_Description ##### -->
+functions for transfering data via the X selection mechanism.
+
+
+<!-- ##### SECTION ./tmpl/selections.sgml:Title ##### -->
+Selections
+
+
+<!-- ##### SECTION ./tmpl/threads.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/threads.sgml:See_Also ##### -->
<para>
-Returns the difference between the union and the intersection of two regions.
-This is a region containing the pixels that are in one of the source regions,
-but which are not in both.
+
</para>
-@source1: a #GdkRegion.
-@source2: a #GdkRegion.
-@Returns: the difference between the union and the intersection of @source1
-and @source2.
-<!-- ##### FUNCTION gdk_input_motion_events ##### -->
+<!-- ##### SECTION ./tmpl/threads.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/threads.sgml:Title ##### -->
+Threads
+
+
+<!-- ##### SECTION ./tmpl/visuals.sgml:Long_Description ##### -->
<para>
-Retrieves the motion history for a given device/window pair.
+The way that the data stored on the screen is stored
+in memory can vary considerably between different X
+servers; some X servers even support multiple formats
+used simultaneously. An X <firstterm>visual</firstterm>
+represents a particular format for screen data.
+It includes information about the number of bits
+used for each color, the way the bits are translated
+into an RGB value for display, and the way the bits
+are stored in memory.
+</para>
+<para>
+There are several standard visuals. The visual returned
+by gdk_visual_get_system() is the system's default
+visual. gdk_rgb_get_visual() return the visual most
+suited to displaying full-color image data. If you
+use the calls in GdkRGB, you should create your windows
+using this visual (and the colormap returned by
+gdk_rgb_get_colormap()).
+</para>
+<para>
+A number of functions are provided for determining
+the "best" available visual. For the purposes of
+making this determination, higher bit depths are
+considered better, and for visuals of the same
+bit depth, %GDK_VISUAL_PSEUDO_COLOR is preferred at
+8bpp, otherwise, the visual types are ranked in the
+order of (highest to lowest) %GDK_VISUAL_DIRECT_COLOR,
+%GDK_VISUAL_TRUE_COLOR, %GDK_VISUAL_PSEUDO_COLOR,
+%GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE,
+then %GDK_VISUAL_STATIC_GRAY.
</para>
-@window: a #GdkWindow.
-@deviceid: the device for which to retrieve motion history.
-@start: the start time.
-@stop: the stop time.
-@nevents_return: location to store the number of events returned.
-@Returns: a newly allocated array containing all the events
- from @start to @stop. This array should be freed
- with g_free() when you are finished using it.
-<!-- ##### SECTION ./tmpl/gdkkeys.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/visuals.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### FUNCTION gdk_keymap_translate_keyboard_state ##### -->
+<!-- ##### SECTION ./tmpl/visuals.sgml:Short_Description ##### -->
+manipulation of visuals.
+
+
+<!-- ##### SECTION ./tmpl/visuals.sgml:Title ##### -->
+Visuals
+
+
+<!-- ##### SECTION ./tmpl/windows.sgml:Long_Description ##### -->
<para>
</para>
-@keymap:
-@hardware_keycode:
-@state:
-@group:
-@keyval:
-@effective_group:
-@level:
-@unused_modifiers:
-@Returns:
-<!-- ##### FUNCTION gdk_keymap_get_entries_for_keyval ##### -->
+<!-- ##### SECTION ./tmpl/windows.sgml:See_Also ##### -->
<para>
</para>
-@keymap:
-@keyval:
-@keys:
-@n_keys:
-@Returns:
-<!-- ##### SECTION ./tmpl/gdkregion.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/windows.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/windows.sgml:Title ##### -->
+Windows
+
+
+<!-- ##### SECTION ./tmpl/x_interaction.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/x_interaction.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/x_interaction.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/x_interaction.sgml:Title ##### -->
+X Window System Interaction
+
+
+<!-- ##### MACRO GDK_CORE_POINTER ##### -->
+<para>
+This macro contains an integer value representing
+the device ID for the core pointer device.
+</para>
+
+
+<!-- ##### STRUCT GdkColorContext ##### -->
+<para>
+
+</para>
+
+@visual:
+@colormap:
+@num_colors:
+@max_colors:
+@num_allocated:
+@mode:
+@need_to_free_colormap:
+@std_cmap_atom:
+@clut:
+@cmap:
+@color_hash:
+@palette:
+@num_palette:
+@fast_dither:
+
+<!-- ##### STRUCT GdkColorContextDither ##### -->
+<para>
+
+</para>
+
+@fast_rgb:
+@fast_err:
+@fast_erg:
+@fast_erb:
+
+<!-- ##### ENUM GdkColorContextMode ##### -->
+<para>
+</para>
+@GDK_CC_MODE_UNDEFINED:
+@GDK_CC_MODE_BW:
+@GDK_CC_MODE_STD_CMAP:
+@GDK_CC_MODE_TRUE:
+@GDK_CC_MODE_MY_GRAY:
+@GDK_CC_MODE_PALETTE:
<!-- ##### STRUCT GdkDeviceInfo ##### -->
<para>
which describe what key press events are generated
for each macro button.
-<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Title ##### -->
-Pango Interaction
-
-
-<!-- ##### FUNCTION gdk_regions_union ##### -->
+<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
<para>
-Returns the union of two regions.
-This is all pixels in either of @source1 or @source2.
+
</para>
-@source1: a #GdkRegion.
-@source2: a #GdkRegion.
-@Returns: the union of @source1 and @source2.
+@GDK_PIXBUF_ALPHA_BILEVEL:
+@GDK_PIXBUF_ALPHA_FULL:
-<!-- ##### FUNCTION gdk_drawable_get_visible_region ##### -->
+<!-- ##### FUNCTION gdk_color_context_add_palette ##### -->
<para>
</para>
-@drawable:
+@cc:
+@palette:
+@num_palette:
@Returns:
-<!-- ##### FUNCTION gdk_colormap_query_color ##### -->
+<!-- ##### FUNCTION gdk_color_context_free ##### -->
<para>
</para>
-@colormap:
-@pixel:
-@result:
+@cc:
-<!-- ##### FUNCTION gdk_event_get_state ##### -->
+<!-- ##### FUNCTION gdk_color_context_free_dither ##### -->
<para>
</para>
-@event:
-@state:
-@Returns:
-
-<!-- ##### SECTION ./tmpl/gdkregion.sgml:Short_Description ##### -->
-
-
+@cc:
-<!-- ##### FUNCTION gdk_window_get_decorations ##### -->
+<!-- ##### FUNCTION gdk_color_context_get_index_from_palette ##### -->
<para>
</para>
-@window:
-@decorations:
+@cc:
+@red:
+@green:
+@blue:
+@failed:
@Returns:
-<!-- ##### FUNCTION gdk_keymap_get_entries_for_keycode ##### -->
+<!-- ##### FUNCTION gdk_color_context_get_pixel ##### -->
<para>
</para>
-@keymap:
-@hardware_keycode:
-@keys:
-@keyvals:
-@n_entries:
+@cc:
+@red:
+@green:
+@blue:
+@failed:
@Returns:
-<!-- ##### FUNCTION gdk_drawable_get_clip_region ##### -->
+<!-- ##### FUNCTION gdk_color_context_get_pixel_from_palette ##### -->
<para>
</para>
-@drawable:
+@cc:
+@red:
+@green:
+@blue:
+@failed:
@Returns:
-<!-- ##### FUNCTION gdk_input_set_key ##### -->
+<!-- ##### FUNCTION gdk_color_context_get_pixels ##### -->
<para>
-Sets the key event generated when a macro button is pressed.
+
</para>
-@deviceid: the device to configure.
-@index: the index of the macro button.
-@keyval: the key value for the #GdkKeypressEvent to generate.
- (a value of 0 means no event will be generated.)
-@modifiers: the modifier field for the generated
- #GdkKeyPressEvent.
+@cc:
+@reds:
+@greens:
+@blues:
+@ncolors:
+@colors:
+@nallocated:
-<!-- ##### FUNCTION gdk_input_list_devices ##### -->
+<!-- ##### FUNCTION gdk_color_context_get_pixels_incremental ##### -->
<para>
-Lists all available input devices, along with their
-configuration information.
+
</para>
-@Returns: A #GList of #GdkDeviceInfo structures. This list
- is internal data of GTK+ and should not be modified
- or freed.
+@cc:
+@reds:
+@greens:
+@blues:
+@ncolors:
+@used:
+@colors:
+@nallocated:
-<!-- ##### STRUCT GdkKeymap ##### -->
+<!-- ##### FUNCTION gdk_color_context_init_dither ##### -->
<para>
</para>
-@parent_instance:
+@cc:
-<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:See_Also ##### -->
+<!-- ##### FUNCTION gdk_color_context_new ##### -->
<para>
</para>
+@visual:
+@colormap:
+@Returns:
-<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
+<!-- ##### FUNCTION gdk_color_context_new_mono ##### -->
<para>
</para>
-@GDK_PIXBUF_ALPHA_BILEVEL:
-@GDK_PIXBUF_ALPHA_FULL:
+@visual:
+@colormap:
+@Returns:
-<!-- ##### FUNCTION gdk_regions_subtract ##### -->
+<!-- ##### FUNCTION gdk_color_context_query_color ##### -->
<para>
-Subtracts one region from another.
-The result is a region containing all the pixels which are in @source1, but
-which are not in @source2.
+
</para>
-@source1: a #GdkRegion.
-@source2: a #GdkRegion to subtract from @source1.
-@Returns: @source1 - @source2.
+@cc:
+@color:
+@Returns:
-<!-- ##### FUNCTION gdk_input_window_get_pointer ##### -->
+<!-- ##### FUNCTION gdk_color_context_query_colors ##### -->
<para>
-Returns information about the current position of the pointer
-within a window, including extended device information.
-Any of the return parameters may be %NULL, in which case,
-they will be ignored.
-</para>
-@window: a #GdkWindow.
-@deviceid: a device ID.
-@x: location to store current x postion.
-@y: location to store current y postion.
-@pressure: location to store current pressure.
-@xtilt: location to store current tilt in the x direction.
-@ytilt: location to store current tilt in the y direction.
-@mask: location to store the current modifier state.
+</para>
-<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Short_Description ##### -->
+@cc:
+@colors:
+@num_colors:
+@Returns:
+<!-- ##### FUNCTION gdk_input_list_devices ##### -->
+<para>
+Lists all available input devices, along with their
+configuration information.
+</para>
+@Returns: A #GList of #GdkDeviceInfo structures. This list
+ is internal data of GTK+ and should not be modified
+ or freed.
-<!-- ##### MACRO GDK_CORE_POINTER ##### -->
+<!-- ##### FUNCTION gdk_input_motion_events ##### -->
<para>
-This macro contains an integer value representing
-the device ID for the core pointer device.
+Retrieves the motion history for a given device/window pair.
</para>
+@window: a #GdkWindow.
+@deviceid: the device for which to retrieve motion history.
+@start: the start time.
+@stop: the stop time.
+@nevents_return: location to store the number of events returned.
+@Returns: a newly allocated array containing all the events
+ from @start to @stop. This array should be freed
+ with g_free() when you are finished using it.
<!-- ##### FUNCTION gdk_input_set_axes ##### -->
<para>
@axes: an array of GdkAxisUse. This length of this array
must match the number of axes for the device.
-<!-- ##### STRUCT GdkSpan ##### -->
+<!-- ##### FUNCTION gdk_input_set_key ##### -->
<para>
-
+Sets the key event generated when a macro button is pressed.
</para>
-@x:
-@y:
-@width:
+@deviceid: the device to configure.
+@index: the index of the macro button.
+@keyval: the key value for the #GdkKeypressEvent to generate.
+ (a value of 0 means no event will be generated.)
+@modifiers: the modifier field for the generated
+ #GdkKeyPressEvent.
-<!-- ##### STRUCT GdkKeyInfo ##### -->
+<!-- ##### FUNCTION gdk_input_set_mode ##### -->
<para>
-
+Enables or disables a device, and determines how the
+device maps onto the screen.
</para>
-@keycode:
-@group:
-@level:
+@deviceid: the device to configure.
+@mode: the new mode.
+@Returns: %TRUE if the device supports the given mode, otherwise
+ %FALSE and the device's mode is unchanged.
<!-- ##### FUNCTION gdk_input_set_source ##### -->
<para>
@deviceid: the device to configure
@source: the new source type.
-<!-- ##### FUNCTION gdk_region_spans_intersect_foreach ##### -->
-<para>
-Intersects a set of spans with a region and call a user specified
-function for each resulting spanline. This function is a lot more effective
-if the spans are sorted.
-</para>
-
-@region: The region to intersect against.
-@spans: Array of spans to intersect.
-@n_spans: Number of spans.
-@sorted: True if the spans are sorted in increasing y order.
-@function: The function to call for each intersected spanline.
-@data: Opaque user data passed to function.
-
-<!-- ##### FUNCTION gdk_keymap_get_default ##### -->
+<!-- ##### FUNCTION gdk_input_window_get_pointer ##### -->
<para>
-
+Returns information about the current position of the pointer
+within a window, including extended device information.
+Any of the return parameters may be %NULL, in which case,
+they will be ignored.
</para>
-@Returns:
-
-<!-- ##### SECTION ./tmpl/gdkregion.sgml:Title ##### -->
-Points, Rectangles and Regions
-
+@window: a #GdkWindow.
+@deviceid: a device ID.
+@x: location to store current x postion.
+@y: location to store current y postion.
+@pressure: location to store current pressure.
+@xtilt: location to store current tilt in the x direction.
+@ytilt: location to store current tilt in the y direction.
+@mask: location to store the current modifier state.
<!-- ##### FUNCTION gdk_regions_intersect ##### -->
<para>
@source2: a #GdkRegion.
@Returns: the intersection of @source1 and @source2.
-<!-- ##### FUNCTION gdk_keymap_lookup_key ##### -->
-<para>
-
-</para>
-
-@keymap:
-@key:
-@Returns:
-
-<!-- ##### USER_FUNCTION GdkSpanFunc ##### -->
-<para>
-
-</para>
-
-@span: The intersected part of the span.
-@data: Opaque data passed by user.
-
-<!-- ##### STRUCT GdkKeymapClass ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Title ##### -->
-Keyboard Handling
-
-
-<!-- ##### STRUCT GdkKeymapKey ##### -->
+<!-- ##### FUNCTION gdk_regions_subtract ##### -->
<para>
-
+Subtracts one region from another.
+The result is a region containing all the pixels which are in @source1, but
+which are not in @source2.
</para>
-@keycode:
-@group:
-@level:
+@source1: a #GdkRegion.
+@source2: a #GdkRegion to subtract from @source1.
+@Returns: @source1 - @source2.
-<!-- ##### FUNCTION gdk_input_set_mode ##### -->
+<!-- ##### FUNCTION gdk_regions_union ##### -->
<para>
-Enables or disables a device, and determines how the
-device maps onto the screen.
+Returns the union of two regions.
+This is all pixels in either of @source1 or @source2.
</para>
-@deviceid: the device to configure.
-@mode: the new mode.
-@Returns: %TRUE if the device supports the given mode, otherwise
- %FALSE and the device's mode is unchanged.
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the union of @source1 and @source2.
-<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Long_Description ##### -->
+<!-- ##### FUNCTION gdk_regions_xor ##### -->
<para>
-
+Returns the difference between the union and the intersection of two regions.
+This is a region containing the pixels that are in one of the source regions,
+but which are not in both.
</para>
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the difference between the union and the intersection of @source1
+and @source2.
Images
<!-- ##### SECTION Short_Description ##### -->
-
+an area for bit-mapped graphics stored on the X Windows client.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GdkImage type represents an area for drawing graphics.
+It has now been superceded to a large extent by the much more flexible
+<link linkend="gdk-GdkRGB">GdkRGB</link> functions.
+</para>
+<para>
+To create an empty #GdkImage use gdk_image_new().
+To create a #GdkImage from bitmap data use gdk_image_new_bitmap().
+To create an image from part of a #GdkWindow use gdk_image_get().
+</para>
+<para>
+The image can be manipulated with gdk_image_get_pixel() and
+gdk_image_put_pixel(), or alternatively by changing the actual pixel data.
+Though manipulating the pixel data requires complicated code to cope with
+the different formats that may be used.
+</para>
+<para>
+To draw a #GdkImage in a #GdkWindow or #GdkPixmap use gdk_draw_image().
+</para>
+<para>
+To destroy a #GdkImage use gdk_image_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+
+<varlistentry>
+<term><link linkend="gdk-Bitmaps-and-Pixmaps">Bitmaps and Pixmaps</link></term>
+<listitem><para>
+Graphics which are stored on the X Windows server.
+Since these are stored on the server they can be drawn very quickly, and all
+of the <link linkend="gdk-Drawing-Primitives">Drawing Primitives</link> can be
+used to draw on them. Their main disadvantage is that manipulating individual
+pixels can be very slow.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><link linkend="gdk-GdkRGB">GdkRGB</link></term>
+<listitem><para>
+Built on top of #GdkImage, this provides much more functionality,
+including the dithering of colors to produce better output on low-color
+displays.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### STRUCT GdkImage ##### -->
<para>
-
+The #GdkImage struct contains information on the image and the pixel data.
</para>
@parent_instance:
-@type:
-@visual:
-@byte_order:
-@width:
-@height:
-@depth:
-@bpp:
-@bpl:
-@mem:
+@type: the type of the image.
+@visual: the visual.
+@byte_order: the byte order.
+@width: the width of the image in pixels.
+@height: the height of the image in pixels.
+@depth: the depth of the image, i.e. the number of bits per pixel.
+@bpp: the number of bytes per pixel.
+@bpl: the number of bytes per line of the image.
+@bits_per_pixel:
+@mem: the pixel data.
@windowing_data:
<!-- ##### FUNCTION gdk_image_new ##### -->
<para>
-
+Creates a new #GdkImage.
</para>
-@type:
-@visual:
-@width:
-@height:
-@Returns:
+@type: the type of the #GdkImage, one of %GDK_IMAGE_NORMAL, %GDK_IMAGE_SHARED
+and %GDK_IMAGE_FASTEST. %GDK_IMAGE_FASTEST is probably the best choice, since
+it will try creating a %GDK_IMAGE_SHARED image first and if that fails it will
+then use %GDK_IMAGE_NORMAL.
+@visual: the #GdkVisual to use for the image.
+@width: the width of the image in pixels.
+@height: the height of the image in pixels.
+@Returns: a new #GdkImage, or NULL if the image could not be created.
<!-- ##### ENUM GdkImageType ##### -->
<para>
-
+Specifies the type of a #GdkImage.
</para>
-@GDK_IMAGE_NORMAL:
-@GDK_IMAGE_SHARED:
-@GDK_IMAGE_FASTEST:
+@GDK_IMAGE_NORMAL: The original X image type, which is quite slow since the
+image has to be transferred from the client to the server to display it.
+@GDK_IMAGE_SHARED: A faster image type, which uses shared memory to transfer
+the image data between client and server. However this will only be available
+if client and server are on the same machine and the shared memory extension
+is supported by the server.
+@GDK_IMAGE_FASTEST: Specifies that %GDK_IMAGE_SHARED should be tried first,
+and if that fails then %GDK_IMAGE_NORMAL will be used.
<!-- ##### FUNCTION gdk_image_new_bitmap ##### -->
<para>
-
+Creates a new #GdkImage with a depth of 1 from the given data.
</para>
-@visual:
-@data:
-@width:
-@height:
-@Returns:
+@visual: the #GdkVisual to use for the image.
+@data: the pixel data.
+@width: the width of the image in pixels.
+@height: the height of the image in pixels.
+@Returns: a new #GdkImage.
<!-- ##### FUNCTION gdk_image_get ##### -->
<para>
-
+Gets part of a #GdkWindow and stores it in a new #GdkImage.
</para>
@drawable:
-@x:
-@y:
-@width:
-@height:
-@Returns:
+@x: the left edge of the rectangle to copy from @window.
+@y: the top edge of the rectangle to copy from @window.
+@width: the width of the area to copy, in pixels.
+@height: the height of the area to copy, in pixels.
+@Returns: a new #GdkImage with a copy of the given area of @window.
+<!-- # Unused Parameters # -->
+@window: the #GdkWindow to copy from.
<!-- ##### FUNCTION gdk_image_ref ##### -->
<!-- ##### MACRO gdk_image_destroy ##### -->
<para>
-
+Destroys a #GdkImage, freeing any resources allocated for it.
</para>
+<!-- # Unused Parameters # -->
+@image: a #GdkImage.
<!-- ##### FUNCTION gdk_image_put_pixel ##### -->
<para>
-
+Sets a pixel in a #GdkImage to a given pixel value.
</para>
-@image:
-@x:
-@y:
-@pixel:
+@image: a #GdkImage.
+@x: the x coordinate of the pixel to set.
+@y: the y coordinate of the pixel to set.
+@pixel: the pixel value to set.
<!-- ##### FUNCTION gdk_image_get_pixel ##### -->
<para>
-
+Gets a pixel value at a specified position in a #GdkImage.
</para>
-@image:
-@x:
-@y:
-@Returns:
+@image: a #GdkImage.
+@x: the x coordinate of the pixel to get.
+@y: the y coordinate of the pixel to get.
+@Returns: the pixel value at the given position.
<!-- ##### STRUCT GdkPoint ##### -->
<para>
-
+Defines the x and y coordinates of a point.
+Note that both are defined as #gint16 values, so the coordinates are limited
+to between -32,768 and 32,767.
</para>
-@x:
-@y:
+@x: the x coordinate of the point.
+@y: the y coordinate of the point.
<!-- ##### STRUCT GdkRectangle ##### -->
<para>
-
+Defines the position and size of a rectangle.
</para>
-@x:
-@y:
-@width:
-@height:
+@x: the x coordinate of the left edge of the rectangle.
+@y: the y coordinate of the top of the rectangle.
+@width: the width of the rectangle.
+@height: the height of the rectangle.
<!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
<para>
-
+Calculates the intersection of two rectangles.
</para>
-@src1:
-@src2:
-@dest:
-@Returns:
+@src1: a #GdkRectangle.
+@src2: a #GdkRectangle.
+@dest: the intersection of @src1 and @src2.
+@Returns: TRUE if the rectangles intersect.
<!-- ##### FUNCTION gdk_rectangle_union ##### -->
<para>
-
+Calculates the union of two rectangles.
+The union of rectangles @src1 and @src2 is the smallest rectangle which
+includes both @src1 and @src2 within it.
</para>
-@src1:
-@src2:
-@dest:
+@src1: a #GdkRectangle.
+@src2: a #GdkRectangle.
+@dest: the union of @src1 and @src2.
<!-- ##### STRUCT GdkRegion ##### -->
GdkRGB
<!-- ##### SECTION Short_Description ##### -->
-
+displays RGB images (as well as grayscale and colormapped) to
+the native window.
<!-- ##### SECTION Long_Description ##### -->
<para>
+GdkRgb converts RGB, grayscale, and colormapped images into the native
+window pixel format and displays them. It takes care of colormaps,
+visuals, dithering, and management of the temporary buffers.
+
+</para>
+
+<para>
+You must call gdk_rgb_init() before using any GdkRgb functionality. If
+you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
+(including #GtkPreview) call gdk_rgb_init() in their class_init method.
+Thus, if you use GdkRgb only indirectly, you don't need to worry
+about it.
+</para>
+
+<para>
+GdkRgb tries to use the system default visual and colormap, but
+doesn't always succeed. Thus, you have to be prepared to install the
+visual and colormap generated by GdkRgb. The following code sequence
+(before any widgets are created) should work in most applications:
+</para>
+
+<informalexample>
+<programlisting>
+ gdk_rgb_init ();
+
+ gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
+ gtk_widget_set_default_visual (gdk_rgb_get_visual ());
+</programlisting>
+</informalexample>
+
+<para>
+You can also push the colormap and visual, but in general it doesn't
+work unless the push wraps the window creation call. If you wrap the
+push around a widget which is embedded in a window without the GdkRgb
+colormap and visual, it probably won't work, and is likely to cause
+colormap flashing, as well.
+</para>
+
+<para>
+On 8-bit systems, the colormaps used by Imlib and GdkRgb may
+conflict. There is no good general solution to this other than phasing
+out the dependence on Imlib.
+</para>
+
+<para>
+You can set the threshold for installing colormaps with
+gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
+of this size or larger can be allocated in the default colormap, then
+that's done. Otherwise, GdkRgb creates its own private colormap.
+Setting it to 0 means that it always tries to use the default
+colormap, and setting it to 216 means that it always creates a private
+one if it cannot allocate the 6x6x6 colormap in the default. If you
+always want a private colormap (to avoid consuming too many colormap
+entries for other apps, say), you can use gdk_rgb_set_install(TRUE).
+Setting the value greater than 216 exercises a bug in older versions
+of GdkRgb. Note, however, that setting it to 0 doesn't let you get
+away with ignoring the colormap and visual - a colormap is always
+created in grayscale and direct color modes, and the visual is changed
+in cases where a "better" visual than the default is available.
</para>
+<example>
+<title>A simple example program using GdkRGB.</title>
+<programlisting>
+#include <gtk/gtk.h>
+
+#define IMAGE_WIDTH 256
+#define IMAGE_HEIGHT 256
+
+guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
+
+gboolean on_darea_expose (GtkWidget *widget,
+ GdkEventExpose *event,
+ gpointer user_data);
+
+int
+main (int argc, char *argv[])
+{
+ GtkWidget *window, *darea;
+ gint x, y;
+ guchar *pos;
+
+ gtk_init (&argc, &argv);
+ gdk_rgb_init ();
+ window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+ darea = gtk_drawing_area_new ();
+ gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
+ gtk_container_add (GTK_CONTAINER (window), darea);
+ gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
+ GTK_SIGNAL_FUNC (on_darea_expose), NULL);
+ gtk_widget_show_all (window);
+
+ /* Set up the RGB buffer. */
+ pos = rgbbuf;
+ for (y = 0; y < IMAGE_HEIGHT; y++)
+ {
+ for (x = 0; x < IMAGE_WIDTH; x++)
+ {
+ *pos++ = x - x % 32; /* Red. */
+ *pos++ = (x / 32) * 4 + y - y % 32; /* Green. */
+ *pos++ = y - y % 32; /* Blue. */
+ }
+ }
+
+ gtk_main ();
+ return 0;
+}
+
+
+gboolean
+on_darea_expose (GtkWidget *widget,
+ GdkEventExpose *event,
+ gpointer user_data)
+{
+ gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
+ 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
+ GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
+}
+</programlisting>
+</example>
+
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
+
+<varlistentry>
+<term>#GdkColor</term>
+<listitem><para>The underlying Gdk mechanism for allocating
+colors.</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### FUNCTION gdk_rgb_init ##### -->
<para>
+Initializes GdkRgb statically. It may be called more than once with no
+ill effects. It must, however, be called before any other GdkRgb
+operations are performed.
+</para>
+<para>
+The GdkRgb "context" is allocated statically. Thus, GdkRgb may be used
+to drive only one visual in any given application. GdkRgb
+automatically selects a best visual and sets its own colormap, if
+necessary. gdk_rgb_get_visual() and gdk_rgb_get_cmap () retrieve
+the chosen visual and colormap, respectively.
</para>
<!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para>
+Draws an RGB image in the drawable. This is the core GdkRgb
+function, and likely the only one you will need to use other than the
+initialization stuff.
+</para>
+<para>
+The @rowstride parameter allows for lines to be aligned more flexibly.
+For example, lines may be allocated to begin on 32-bit boundaries,
+even if the width of the rectangle is odd. Rowstride is also useful
+when drawing a subrectangle of a larger image in memory. Finally, to
+replicate the same line a number of times, the trick of setting
+@rowstride to 0 is allowed.
</para>
-@drawable:
-@gc:
-@x:
-@y:
-@width:
-@height:
-@dith:
-@rgb_buf:
-@rowstride:
+<para>
+In general, for 0 <= i < @width and 0 <= j < height,
+the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
+@rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
+1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
+</para>
+
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context (all Gdk drawing operations require one; its
+contents are ignored).
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode.
+@rgb_buf: The pixel data, represented as packed 24-bit data.
+@rowstride: The number of bytes from the start of one row in @rgb_buf to the
+start of the next.
<!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
<para>
+Draws an RGB image in the drawable, with an adjustment for dither alignment.
+</para>
+<para>
+This function is useful when drawing dithered images into a window
+that may be scrolled. Pixel (x, y) will be drawn dithered as if its
+actual location is (x + @xdith, y + @ydith). Thus, if you draw an
+image into a window using zero dither alignment, then scroll up one
+pixel, subsequent draws to the window should have @ydith = 1.
</para>
-@drawable:
-@gc:
-@x:
-@y:
-@width:
-@height:
-@dith:
-@rgb_buf:
-@rowstride:
-@xdith:
-@ydith:
+<para>
+Setting the dither alignment correctly allows updating of small parts
+of the screen while avoiding visible "seams" between the different
+dither textures.
+</para>
+
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode.
+@rgb_buf: The pixel data, represented as packed 24-bit data.
+@rowstride: The number of bytes from the start of one row in @rgb_buf to the
+start of the next.
+@xdith: An x offset for dither alignment.
+@ydith: A y offset for dither alignment.
<!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
<para>
-
+Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
+actual colors to the color indices.
</para>
-@drawable:
-@gc:
-@x:
-@y:
-@width:
-@height:
-@dith:
-@buf:
-@rowstride:
-@cmap:
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode.
+@buf: The pixel data, represented as 8-bit color indices.
+@rowstride: The number of bytes from the start of one row in @buf to the
+start of the next.
+@cmap: The #GdkRgbCmap used to assign colors to the color indices.
<!-- ##### FUNCTION gdk_draw_gray_image ##### -->
<para>
+Draws a grayscale image in the drawable.
</para>
-@drawable:
-@gc:
-@x:
-@y:
-@width:
-@height:
-@dith:
-@buf:
-@rowstride:
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode.
+@buf: The pixel data, represented as 8-bit gray values.
+@rowstride: The number of bytes from the start of one row in @buf to the
+start of the next.
<!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
<para>
+Draws a padded RGB image in the drawable. The image is stored as one
+pixel per 32-bit word. It is laid out as a red byte, a green byte, a
+blue byte, and a padding byte.
+</para>
+<para>
+It's unlikely that this function will give significant performance
+gains in practice. In my experience, the performance gain from having
+pixels aligned to 32-bit boundaries is cancelled out by the increased
+memory bandwidth.
</para>
-@drawable:
-@gc:
-@x:
-@y:
-@width:
-@height:
-@dith:
-@buf:
-@rowstride:
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode.
+@buf: The pixel data, represented as padded 32-bit data.
+@rowstride: The number of bytes from the start of one row in @buf to the
+start of the next.
<!-- ##### FUNCTION gdk_draw_rgb_32_image_dithalign ##### -->
<!-- ##### ENUM GdkRgbDither ##### -->
<para>
+Selects whether or not GdkRgb applies dithering
+to the image on display. There are three values:
+</para>
+
+<itemizedlist>
+
+<listitem>
+<para>
+%GDK_RGB_DITHER_NONE: Never use dithering.
+</para>
+</listitem>
+
+<listitem>
+<para>
+%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
+only.
+</para>
+</listitem>
+
+<listitem>
+<para>
+%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
+</para>
+</listitem>
+
+</itemizedlist>
+
+<para>
+Since GdkRgb currently only handles images with 8 bits per component,
+dithering on 24 bit per pixel displays is a moot point.
</para>
@GDK_RGB_DITHER_NONE:
<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
<para>
-
+Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
+RGB colors. If @n_colors is less than 256, then images containing
+color values greater than or equal to @n_colors will produce undefined
+results, including possibly segfaults.
</para>
-@colors:
-@n_colors:
-@Returns:
+@colors: The colors, represented as 0xRRGGBB integer values.
+@n_colors: The number of colors in the cmap.
+@Returns: The newly created #GdkRgbCmap
<!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
<para>
-
+Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
</para>
-@cmap:
+@cmap: The #GdkRgbCmap to free.
<!-- ##### STRUCT GdkRgbCmap ##### -->
<para>
-
+A private data structure which maps color indices to actual RGB
+colors. This is used only for gdk_draw_indexed_image().
</para>
@colors:
<!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
<para>
-
+Sets the foreground color in @gc to the specified color (or the
+closest approximation, in the case of limited visuals).
</para>
-@gc:
-@rgb:
+@gc: The #GdkGC to modify.
+@rgb: The color, represented as a 0xRRGGBB integer value.
<!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
<para>
-
+Sets the background color in @gc to the specified color (or the
+closest approximation, in the case of limited visuals).
</para>
-@gc:
-@rgb:
+@gc: The #GdkGC to modify.
+@rgb: The color, represented as a 0xRRGGBB integer value.
<!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
<para>
-
+Finds the X pixel closest in color to the @rgb color specified. This
+value may be used to set the <structfield>pixel</structfield> field of
+a #GdkColor struct.
</para>
-@rgb:
-@Returns:
+@rgb: The color, represented as a 0xRRGGBB integer value.
+@Returns: The X pixel value.
<!-- ##### FUNCTION gdk_rgb_find_color ##### -->
<!-- ##### FUNCTION gdk_rgb_set_install ##### -->
<para>
+If @install is TRUE, directs GdkRgb to always install a new "private"
+colormap rather than trying to find a best fit with the colors already
+allocated. Ordinarily, GdkRgb will install a colormap only if a
+sufficient cube cannot be allocated.
+</para>
+<para>
+A private colormap has more colors, leading to better quality display,
+but also leads to the dreaded "colormap flashing" effect.
</para>
-@install:
+@install: TRUE to set install mode.
<!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
<para>
-
+Sets the minimum number of colors for the color cube. Generally,
+GdkRgb tries to allocate the largest color cube it can. If it can't
+allocate a color cube at least as large as @min_colors, it installs a
+private colormap.
</para>
-@min_colors:
+@min_colors: The minimum number of colors accepted.
<!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
<para>
-
+Gets the visual chosen by GdkRgb. This visual and the corresponding
+colormap should be used when creating windows that will be drawn in by GdkRgb.
</para>
-@Returns:
+@Returns: The #GdkVisual chosen by GdkRgb.
<!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
<!-- ##### MACRO gdk_rgb_get_cmap ##### -->
<para>
-
+Gets the colormap set by GdkRgb. This colormap and the corresponding
+visual should be used when creating windows that will be drawn in by GdkRgb.
</para>
+@Returns: The #GdkColormap set by GdkRgb.
<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
<para>
-
+Determine whether the visual is ditherable. This function may be
+useful for presenting a user interface choice to the user about which
+dither mode is desired; if the display is not ditherable, it may make
+sense to gray out or hide the corresponding UI widget.
</para>
-@Returns:
+@Returns: TRUE if the visual is ditherable.
<!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
<para>
-
+Sets the "verbose" flag. This is generally only useful for debugging.
</para>
-@verbose:
+@verbose: TRUE if verbose messages are desired.
@decorations:
+<!-- ##### FUNCTION gdk_window_get_decorations ##### -->
+<para>
+
+</para>
+
+@window: The window to get the decorations from
+@decorations: The window decorations will be written here
+@Returns: TRUE if the window has decorations set, FALSE otherwise.
+
+
<!-- ##### ENUM GdkWMDecoration ##### -->
<para>
# The top-level SGML file.
DOC_MAIN_SGML_FILE=gtk-docs.sgml
-# The directory containing the source code
-DOC_SOURCE_DIR=$(top_srcdir)/gtk
+# The directory containing the source code. Relative to $(srcdir)
+DOC_SOURCE_DIR=../../../gtk
+
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS=--deprecated-guards="GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED"
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS=
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+# Used for dependencies
+HFILE_GLOB=$(top_srcdir)/gtk/*.h
+CFILE_GLOB=$(top_srcdir)/gtk/*.c
+
# Header files to ignore when scanning
IGNORE_HFILES= \
fnmatch.h \
gtktexttypes.h \
gtktypebuiltins.h
+# Images to copy into HTML directory
+HTML_IMAGES =
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
+content_files = \
+ compiling.sgml \
+ framebuffer.sgml \
+ objects_grouped.sgml \
+ text_widget.sgml \
+ tree_widget.sgml
+
+# Other files to distribute
+extra_files =
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed
+# if $(DOC_MODULE).types is non-empty.
GTKDOC_CFLAGS = @STRIP_BEGIN@ \
@CFLAGS@ \
-I$(top_srcdir) \
GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
-content_files = \
- objects_grouped.sgml \
- text_widget.sgml \
- tree_widget.sgml
####################################
# Everything below here is generic #
TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
EXTRA_DIST = \
- $(DOC_MODULE).types \
- $(DOC_MAIN_SGML_FILE) \
$(content_files) \
+ $(extra_files) \
+ $(HTML_IMAGES) \
+ $(DOC_MAIN_SGML_FILE) \
+ $(DOC_MODULE).types \
$(DOC_MODULE)-sections.txt \
$(DOC_MODULE)-overrides.txt
+DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp
+
if ENABLE_GTK_DOC
-all-local: html/index.html
+all-local: html-build.stamp
+
+SCANOBJ_FILES = \
+ $(DOC_MODULE).args \
+ $(DOC_MODULE).hierarchy \
+ $(DOC_MODULE).signal
+
+scan-build.stamp: $(HFILE_GLOB)
+ @echo '*** Scanning header files ***'
+ cd $(srcdir) && ( \
+ if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \
+ else \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
+ fi )
+ cd $(srcdir) && \
+ gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
+ touch scan-build.stamp
-$(DOC_MODULE)-decl.txt:
- $(MAKE) scan
+check_scan:
+ $(MAKE) scan-build.stamp
-$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
- $(MAKE) templates
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan
-sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt
- $(MAKE) sgml
+tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
+ @echo '*** Rebuilding template files ***'
+ cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+ touch tmpl-build.stamp
-html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE) $(content_files)
- $(MAKE) html
-endif
+check_templates:
+ $(MAKE) tmpl-build.stamp
-scan:
- (cd $(srcdir) \
- && CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) \
- && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --deprecated-guards="GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED" --ignore-headers="$(IGNORE_HFILES)" $(EXTRA_HFILES))
+tmpl.stamp: check_templates
-templates:
- cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+sgml-build.stamp: tmpl.stamp $(CFILE_GLOB)
+ @echo '*** Building SGML ***'
+ cd $(srcdir) && \
+ gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
+ touch sgml-build.stamp
+
+check_sgml:
+ $(MAKE) sgml-build.stamp
-sgml:
- cd $(srcdir) \
- && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR)
+sgml.stamp: check_sgml
-html:
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE)
+ @echo '*** Building HTML ***'
test -d $(srcdir)/html || mkdir $(srcdir)/html
- -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
@echo '-- Fixing Crossreferences'
cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
+ touch html-build.stamp
+endif
clean-local:
- rm -f *~ *.bak *.signals *-unused.txt
+ rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp
maintainer-clean-local: clean
cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
dist-check-gtkdoc:
else
dist-check-gtkdoc:
- @echo "*** gtk-doc must be installed and enabled in order to make dist
+ @echo "*** gtk-doc must be installed and enabled in order to make dist"
@false
endif
-dist-hook: dist-check-gtkdoc
- mkdir $(distdir)/html
- mkdir $(distdir)/sgml
+dist-hook: dist-check-gtkdoc dist-hook-local
mkdir $(distdir)/tmpl
- -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(srcdir)/html/index.sgml $(distdir)/html
+ mkdir $(distdir)/sgml
+ mkdir $(distdir)/html
-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
+ -cp $(srcdir)/html/index.sgml $(distdir)/html
+ -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
+ for i in $(HTML_IMAGES) ; do \
+ cp $(srcdir)/$$i $(distdir)/html ; \
+ done
-.PHONY : html sgml templates scan
+.PHONY : check_sgml check_templates check_scan dist-hook-local
-<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Title ##### -->
-Debugging
-
-
-<!-- ##### SIGNAL GtkEditable::cut-clipboard ##### -->
-<para>
-An action signal. Causes the characters in the current
-selection to be copied to the clipboard and then deleted from
-the widget.
-</para>
-
-@editable: the object which received the signal.
-
-<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Short_Description ##### -->
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__BOXED ##### -->
+<!-- ##### SECTION ./tmpl/gtkaccelgroup.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### FUNCTION gtk_model_simple_node_inserted ##### -->
+<!-- ##### SECTION ./tmpl/gtkaccelgroup.sgml:See_Also ##### -->
<para>
</para>
-@simple:
-@path:
-@iter:
-<!-- ##### FUNCTION gtk_widget_newv ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkaccelgroup.sgml:Short_Description ##### -->
-</para>
-@type:
-@nargs:
-@args:
-@Returns:
-<!-- ##### MACRO GTK_CLIST_CHILD_HAS_FOCUS ##### -->
-<para>
-A macro to check whether a child widget of the CList
-has the focus.
-</para>
+<!-- ##### SECTION ./tmpl/gtkaccelgroup.sgml:Title ##### -->
+Keyboard Accelerators
-@clist: The #GtkCList widget to check.
-<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Long_Description ##### -->
-<refsect2>
-<title>What are Signal Marshallers?</title>
+<!-- ##### SECTION ./tmpl/gtkarg.sgml:Long_Description ##### -->
<para>
-Marshals are functions which all have the same prototype:
-they take a #GtkObject, a #GtkSignalFunc, a #gpointer,
-and an array of argument values.
-The functions are names gtk_marshall_RETURNTYPE__PARAMTYPE1_PARAMTYPE2....
+All the functions in here are marked a Non-public.
+We describe it anyway because it is occasionally useful
+to understand how the work is done.
</para>
<para>
-They then call a native function: the GtkObject is the first
-parameter passed in. The arguments are passed in the native
-calling convention: chars, shorts, ints, longs may be packed
-on the stack, or tucked in registers: it doesn't matter
-because the same calling convention will be generated
-inside the gtkmarshal code as is expected where you define
-your handlers.
-</para>
+Arguments are a way of describing a named parameter to a function.
+They have two important roles within gtk+:
+<itemizedlist>
+<listitem>
<para>
-So the function named:
-<programlisting>
-gtk_marshal_BOOL__POINTER_INT_INT_UINT(GtkObject*, GtkSignalFunc, gpointer, GtkArg*);
-</programlisting>
-will call the #GtkSignalFunc assuming it was a function with signature:
-<programlisting>
-gboolean sigfunc(gpointer,gint,gint,guint);
-</programlisting>
+they describe <wordasword>object properties</wordasword>.
+This means that they present an interface to get and set a named-type
+for any type of object in a consistent way.
+(All the relevant functions to do this start with gtk_object_set
+or gtk_object_get).
</para>
-</refsect2>
-<refsect2>
-<title>Writing Custom Marshals</title>
+</listitem>
+<listitem>
<para>
-Marshals are primarily used as arguments to gtk_signal_new().
-Sometimes, you may find that a marshaller you need isn't available
-in the standard list. Then you have to write your own.
+they describe <wordasword>signal arguments</wordasword>.
+This is a lot less often needed but still useful.
+Usually if you are just emitting or creating a particular signal
+it is more convenient to just use gtk_signal_emit() or gtk_signal_new().
+However if you are writing a function to emit or create an arbitrary
+signal, you must use gtk_signal_emitv() or gtk_signal_newv().
+</para>
+</listitem>
+</itemizedlist>
</para>
-<para>
-If you wish to define a signal with a new type of argument list.
-Suppose you want 2 pointers and 2 integers.
-You would write:
-<programlisting>
-typedef int (*GtkSignal_INT__POINTER_POINTER_INT_INT)(
- gpointer, gpointer, gint, gint
-);
-void marshal_INT__POINTER_POINTER_INT_INT(GtkObject* object,
- GtkSignalFunc func,
- gpointer func_data,
- GtkArg* args)
-{
- GtkSignal_NONE__POINTER_POINTER_INT_INT rfunc;
- gint* return_val;
- return_val = GTK_RETLOC_INT(args[4]);
- rfunc = (GtkSignal_INT__POINTER_POINTER_INT_INT)func;
- *return_val = (*rfunc)(object,
- GTK_VALUE_POINTER(args[0]),
- GTK_VALUE_POINTER(args[1]),
- GTK_VALUE_INT(args[2]),
- GTK_VALUE_INT(args[3]),
- func_data);
-}
-</programlisting>
+
+<!-- ##### SECTION ./tmpl/gtkarg.sgml:See_Also ##### -->
+<para>
+#GtkObject.
</para>
-</refsect2>
-<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/gtkarg.sgml:Short_Description ##### -->
+Utility function to manipulate lists of named, typed arguments.
+<!-- ##### SECTION ./tmpl/gtkarg.sgml:Title ##### -->
+Implementation of Object Properties
-<!-- ##### FUNCTION gtk_object_class_add_signals ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkbindings.sgml:Long_Description ##### -->
<para>
-Add an array of signals to a #GtkObjectClass.
-Usually this is called when registering a new type of object.
+
</para>
-@klass: the object class to append signals to.
-@signals: the signals to append.
-@nsignals: the number of signals being appended.
-<!-- ##### MACRO gtk_marshal_NONE__UINT_STRING ##### -->
+<!-- ##### SECTION ./tmpl/gtkbindings.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### MACRO GTK_PRIVATE_UNSET_FLAG ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkbindings.sgml:Short_Description ##### -->
-</para>
-@wid:
-@flag:
-<!-- ##### MACRO GTK_WIDGET_REDRAW_PENDING ##### -->
+<!-- ##### SECTION ./tmpl/gtkbindings.sgml:Title ##### -->
+Bindings
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrenderer.sgml:Long_Description ##### -->
<para>
</para>
-@obj:
-<!-- ##### FUNCTION gtk_icon_factory_get_type ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderer.sgml:See_Also ##### -->
<para>
</para>
-@Returns:
-<!-- ##### ARG GtkTextTag:offset-set ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkcellrenderer.sgml:Short_Description ##### -->
-</para>
-<!-- ##### FUNCTION gtk_theme_engine_create_rc_style ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderer.sgml:Title ##### -->
+GtkCellRenderer
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrendererpixbuf.sgml:Long_Description ##### -->
<para>
</para>
-@engine:
-@Returns:
-<!-- ##### FUNCTION gtk_tree_selection_set_type ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrendererpixbuf.sgml:See_Also ##### -->
<para>
</para>
-@selection:
-@type:
-<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkcellrendererpixbuf.sgml:Short_Description ##### -->
-</para>
-<!-- ##### FUNCTION gtk_tree_store_new_with_values ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrendererpixbuf.sgml:Title ##### -->
+GtkCellRendererPixbuf
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrenderertext.sgml:Long_Description ##### -->
<para>
</para>
-@n_columns:
-@Varargs:
-@Returns:
-<!-- ##### SIGNAL GtkTextView::insert ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderertext.sgml:See_Also ##### -->
<para>
</para>
-@textview: the object which received the signal.
-@arg1:
-<!-- ##### MACRO gtk_widget_set_default_visual ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderertext.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrenderertext.sgml:Title ##### -->
+GtkCellRendererText
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrenderertextpixbuf.sgml:Long_Description ##### -->
<para>
</para>
-@v:
-@visual:
-<!-- ##### FUNCTION gtk_window_set_focus ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderertextpixbuf.sgml:See_Also ##### -->
<para>
</para>
-@window:
-@focus:
-<!-- ##### SECTION ./tmpl/gtkprivate.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderertextpixbuf.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrenderertextpixbuf.sgml:Title ##### -->
+GtkCellRendererTextPixbuf
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrenderertoggle.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### FUNCTION gtk_widget_get ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderertoggle.sgml:See_Also ##### -->
<para>
</para>
-@widget:
-@arg:
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_ENUM ##### -->
+<!-- ##### SECTION ./tmpl/gtkcellrenderertoggle.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gtkcellrenderertoggle.sgml:Title ##### -->
+GtkCellRendererToggle
+
+
+<!-- ##### SECTION ./tmpl/gtkclipboard.sgml:Long_Description ##### -->
+ <para>
+ The #GtkClipboard object represents a clipboard of data shared
+ between different processes or between different widgets in
+ the same process. Each clipboard is identified by a name encoded as a
+ #GdkAtom. (Conversion to and from strings can be done with
+ gdk_atom_intern() and gdk_atom_name().) The default clipboard
+ corresponds to the CLIPBOARD atom; another commonly used clipboard
+ is the PRIMARY clipboard, which, in X, traditionally contains
+ the currently selected text.
+ </para>
+ <para>
+ To support having a number of different formats on the clipboard
+ at the same time, the clipboard mechanism allows providing
+ callbacks instead of the actual data. When you set the contents
+ of the clipboard, you can either supply the data directly (via
+ functions like gtk_clipboard_set_text()), or you can supply a
+ callback to be called at a later time when the data is needed (via
+ gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().)
+ Providing a callback also avoids having to make copies of the data
+ when it is not needed.
+ </para>
+ <para>
+ gtk_clipboard_set_with_data() and gtk_clipboard_set_with_owner()
+ are quite similar; the choice between the two depends mostly on
+ which is more convenient in a particular situation.
+ The former is most useful when you want to have a blob of data
+ with callbacks to convert it into the various data types that you
+ advertise. When the @clear_func you provided is called, you
+ simply free the data blob. The latter is more useful when the
+ contents of clipboard reflect the internal state of a @GObject
+ (As an example, for the PRIMARY clipboard, when an entry widget
+ provides the clipboard's contents the contents are simply the
+ text within the selected region.) If the contents change, the
+ entry widget can call gtk_clipboard_set_with_owner() to update
+ the timestamp for clipboard ownership, without having to worry
+ about @clear_func being called.
+ </para>
+ <para>
+ Requesting the data from the clipboard is essentially
+ asynchronous. If the contents of the clipboard are provided within
+ the same process, then a direct function call will be made to
+ retrieve the data, but if they are provided by another process,
+ then the data needs to be retrieved from the other process, which
+ may take some time. To avoid blocking the user interface, the call
+ to request the selection, gtk_clipboard_request_contents() takes a
+ callback that will be called when the contents are received (or
+ when the request fails.) If you don't want to deal with providing
+ a separate callback, you can also use gtk_clipboard_wait_for_contents().
+ What this does is run the Glib main loop recursively waiting for
+ the contents. This can simplify the code flow, but you still have
+ to be aware that other callbacks in your program can be called
+ while this recursive mainloop is running.
+ </para>
+ <para>
+ Along with the functions to get the clipboard contents as an
+ arbitrary data chunk, there are also functions to retrieve
+ it as text, gtk_clipboard_request_text() and
+ gtk_clipboard_wait_for_text(). These functions take care of
+ determining which formats are advertised by the clipboard
+ provider, asking for the clipboard in the best available format
+ and converting the results into the UTF-8 encoding. (The standard
+ form for representing strings in GTK+.)
+ </para>
+
+
+<!-- ##### SECTION ./tmpl/gtkclipboard.sgml:See_Also ##### -->
<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkSelection</term>
+<listitem><para>@GtkClipboard provides a high-level wrapper around the
+ lower level routines that deal with X selections. It is
+ also possibly to directly manipulate the X selections,
+ though it is seldom necessary to do so.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-<!-- ##### ARG GtkEditable:editable ##### -->
+<!-- ##### SECTION ./tmpl/gtkclipboard.sgml:Short_Description ##### -->
+Storing data on Clipboards.
+
+
+<!-- ##### SECTION ./tmpl/gtkclipboard.sgml:Title ##### -->
+Clipboards
+
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Long_Description ##### -->
<para>
-A boolean indicating whether the widget is editable by
-the user.
+
</para>
-<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### FUNCTION gtk_font_selection_set_filter ##### -->
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Title ##### -->
+Debugging
+
+
+<!-- ##### SECTION ./tmpl/gtkdnd.sgml:Long_Description ##### -->
<para>
-Sets one of the two font filters, to limit the fonts shown.
+GTK+ has a rich set of functions for doing inter-process
+communication via the drag-and-drop metaphore. GTK+
+can do drag and drop (DND) via multiple protocols.
+The currently supported protocols are the Xdnd and
+Motif protocols.
+
+As well as the functions listed here, applications
+may need to use some facilities provided for
+<link linkend="gtk-Selections">Selections</link>.
+Also, the Drag and Drop API makes use of signals
+in the #GtkWidget class.
</para>
-@fontsel: a #GtkFontSelection.
-@filter_type: which of the two font filters to set, either
-#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter
-can be changed by the user, but the base filter is permanent.
-@font_type: the types of font to be shown. This is a bitwise combination of
-#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP,
-or #GTK_FONT_ALL to show all three font types.
-@foundries: a NULL-terminated array of strings containing foundry names which
-will be shown, or NULL to show all foundries.
-@weights: a NULL-terminated array of strings containing weight names which
-will be shown, or NULL to show all weights.
-@slants: a NULL-terminated array of strings containing slant names which
-will be shown, or NULL to show all slants.
-@setwidths: a NULL-terminated array of strings containing setwidth names which
-will be shown, or NULL to show all setwidths.
-@spacings: a NULL-terminated array of strings containing spacings which
-will be shown, or NULL to show all spacings.
-@charsets: a NULL-terminated array of strings containing charset names which
-will be shown, or NULL to show all charsets.
-<!-- ##### FUNCTION gtk_container_unregister_toplevel ##### -->
+<!-- ##### SECTION ./tmpl/gtkdnd.sgml:See_Also ##### -->
<para>
</para>
-@container:
-<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Title ##### -->
-Signal Marshallers
+<!-- ##### SECTION ./tmpl/gtkdnd.sgml:Short_Description ##### -->
+Functions for controlling drag and drop handling.
+
+
+<!-- ##### SECTION ./tmpl/gtkdnd.sgml:Title ##### -->
+Drag and Drop
<!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:Long_Description ##### -->
</para>
-<!-- ##### STRUCT GtkTypeQuery ##### -->
+<!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:See_Also ##### -->
<para>
-A structure used to return values from @gtk_type_query.
+
</para>
-@type:
-@type_name:
-@object_size:
-@class_size:
-<!-- ##### MACRO gtk_widget_pop_visual ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:Short_Description ##### -->
-</para>
-@v:
-<!-- ##### FUNCTION gtk_text_buffer_get_clipboard_contents ##### -->
+<!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:Title ##### -->
+gtkenums.sgml
+
+
+<!-- ##### SECTION ./tmpl/gtkenums.sgml:Long_Description ##### -->
<para>
</para>
-@buffer:
-@Returns:
-<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK ##### -->
+<!-- ##### SECTION ./tmpl/gtkenums.sgml:See_Also ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### ARG GtkTextTag:justify ##### -->
-<para>
-A #GtkJustification for the text. This is only used when the tag is
-applied to the first character in a paragraph.
-</para>
+<!-- ##### SECTION ./tmpl/gtkenums.sgml:Short_Description ##### -->
+Public enumerated types used throughout GTK+.
-<!-- ##### USER_FUNCTION GtkSignalMarshal ##### -->
+<!-- ##### SECTION ./tmpl/gtkenums.sgml:Title ##### -->
+Standard Enumerations
+
+
+<!-- ##### SECTION ./tmpl/gtkfeatures.sgml:Long_Description ##### -->
<para>
-This is currently a hack left in for a scheme wrapper library.
-It may be removed.
+This section describes the variables and functions available to test the
+version of the GTK+ library in use.
+FIXME: probably merge with other general stuff.
</para>
+
+
+<!-- ##### SECTION ./tmpl/gtkfeatures.sgml:See_Also ##### -->
<para>
-Don't use it.
+
</para>
-@object: The object which emits the signal.
-@data: The user data associated with the hook.
-@nparams: The number of parameters to the function.
-@args: The actual values of the arguments.
-@arg_types: The types of the arguments.
-@return_type: The type of the return value from the function
-or #GTK_TYPE_NONE for no return value.
-<!-- ##### FUNCTION gtk_signal_add_emission_hook_full ##### -->
-<para>
-Add an emission hook for a type of signal, for any object.
-(with control of what happens when the hook is
-destroyed).
-</para>
+<!-- ##### SECTION ./tmpl/gtkfeatures.sgml:Short_Description ##### -->
+variables and functions to check the GTK+ version.
-@signal_id: the type of signal add the hook for.
-@hook_func: the function to invoke to handle the hook.
-@data: the user data passed in to hook_func.
-@destroy: a function to invoke when the hook is destroyed,
-to clean up any allocation done just for this
-signal handler.
-@Returns: the id (that you may pass as a parameter
-to gtk_signal_remove_emission_hook()).
-<!-- ##### FUNCTION gtk_text_buffer_paste_primary_selection ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkfeatures.sgml:Title ##### -->
+Version Information
+
+<!-- ##### SECTION ./tmpl/gtkgc.sgml:Long_Description ##### -->
+<para>
+These functions provide access to a shared pool of #GdkGC objects.
+When a new #GdkGC is needed, gtk_gc_get() is called with the required depth,
+colormap and #GdkGCValues. If a #GdkGC with the required properties already
+exists then that is returned. If not, a new #GdkGC is created.
+When the #GdkGC is no longer needed, gtk_gc_release() is called.
</para>
-@buffer:
-@override_location:
-@time:
-@interactive:
-@default_editable:
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT ##### -->
+<!-- ##### SECTION ./tmpl/gtkgc.sgml:See_Also ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### FUNCTION gtk_model_simple_node_changed ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkgc.sgml:Short_Description ##### -->
+provides access to a shared pool of #GdkGC objects.
-</para>
-@simple:
-@path:
-@iter:
+<!-- ##### SECTION ./tmpl/gtkgc.sgml:Title ##### -->
+Graphics Contexts
-<!-- ##### FUNCTION gtk_tree_view_column_set_size ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkiconfactory.sgml:Long_Description ##### -->
<para>
+ An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a
+ set of variants of a particular icon (i.e. a #GtkIconSet contains variants for
+ different sizes and widget states). Icons in an icon factory are named by a
+ stock ID, which is a simple string identifying the icon. Each #GtkStyle has a
+ list of #GtkIconFactory derived from the current theme; those icon factories
+ are consulted first when searching for an icon. If the theme doesn't set a
+ particular icon, GTK+ looks for the icon in a list of default icon factories,
+ maintained by gtk_icon_factory_add_default() and
+ gtk_icon_factory_remove_default(). Applications with icons should add a default
+ icon factory with their icons, which will allow themes to override the icons
+ for the application.
+</para>
+<para>
+To display an icon, always use gtk_style_lookup_icon_set() on the widget that
+will display the icon, or the convenience function
+gtk_widget_render_icon(). These functions take the theme into account when
+looking up the icon to use for a given stock ID.
</para>
-@tree_column:
-@size:
-@width:
-<!-- ##### SIGNAL GtkTextView::copy-text ##### -->
+<!-- ##### SECTION ./tmpl/gtkiconfactory.sgml:See_Also ##### -->
<para>
</para>
-@textview: the object which received the signal.
-<!-- ##### FUNCTION gtk_text_view_get_iter_at_pixel ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkiconfactory.sgml:Short_Description ##### -->
-</para>
+Manipulating stock icons
-@text_view:
-@iter:
-@x:
-@y:
-<!-- ##### FUNCTION gtk_object_getv ##### -->
-<para>
-Gets an array of argument values from an object.
-</para>
+<!-- ##### SECTION ./tmpl/gtkiconfactory.sgml:Title ##### -->
+Themeable Stock Images
-@object: the object to get arguments from.
-@n_args: the number of arguments to query.
-@args: the arguments to fill in.
-<!-- ##### STRUCT GtkThemeEngine ##### -->
+<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### FUNCTION gtk_text_buffer_get_tags ##### -->
+<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:See_Also ##### -->
<para>
</para>
-@buffer:
-@iter:
-@Returns:
-<!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:Short_Description ##### -->
-<!-- ##### FUNCTION gtk_identifier_get_type ##### -->
-<para>
-Get the type of GtkIdentifier.
-</para>
+<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:Title ##### -->
+GtkIMContextSimple
-@Returns: GtkType -- the enumerated type of something.
-<!-- ##### FUNCTION gtk_theme_engine_get ##### -->
+<!-- ##### SECTION ./tmpl/gtkliststore.sgml:Long_Description ##### -->
<para>
</para>
-@name:
-@Returns:
-<!-- ##### STRUCT GtkModelSimple ##### -->
+<!-- ##### SECTION ./tmpl/gtkliststore.sgml:See_Also ##### -->
<para>
</para>
-@parent:
-@stamp:
-<!-- ##### MACRO gtk_marshal_BOOL__POINTER_INT_INT_UINT ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkliststore.sgml:Short_Description ##### -->
-</para>
-<!-- ##### FUNCTION gtk_model_simple_node_child_toggled ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkliststore.sgml:Title ##### -->
+GtkListStore
+
+<!-- ##### SECTION ./tmpl/gtkmain.sgml:Long_Description ##### -->
+<para>
+GTK uses an event oriented programming model. While conventional C programs
+have control over the program flow all the time this does not apply to
+applications written using GTK. Instead you set up some objects and
+register some functions (<quote>callbacks</quote>) to be called whenever
+some event occurs and give control to the GTK mainloop (e.g. by calling
+gtk_main).
</para>
-@simple:
-@path:
-@iter:
+<example>
+<title> Typical <function>main</function> function for a GTK application</title>
+<programlisting>
+int
+main (int argc, char **argv)
+{
+ /* Initialize i18n support */
+ gtk_set_locale ();
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER ##### -->
-<para>
+ /* Initialize the widget set */
+ gtk_init (&argc, &argv);
-</para>
+ /* Create the main window */
+ mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL);
-@object:
-@func:
-@func_data:
-@args:
+ /* Set up our GUI elements */
+ ...
-<!-- ##### FUNCTION gtk_theme_engine_ref ##### -->
-<para>
+ /* Show the application window */
+ gtk_widget_showall (mainwin);
-</para>
+ /* Let the user interact with our application */
+ gtk_main ();
-@engine:
+ /* The user lost interest */
+ gtk_exit (0);
+}
+</programlisting>
+</example>
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkmain.sgml:See_Also ##### -->
+<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### ENUM GtkCellRendererType ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkmain.sgml:Short_Description ##### -->
+Mainloop and event handling
-</para>
-@GTK_CELL_RENDERER_SELECTED:
-@GTK_CELL_RENDERER_PRELIT:
-@GTK_CELL_RENDERER_INSENSITIVE:
+<!-- ##### SECTION ./tmpl/gtkmain.sgml:Title ##### -->
+General
-<!-- ##### FUNCTION gtk_marshal_NONE__NONE ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Long_Description ##### -->
+<refsect2>
+<title>What are Signal Marshallers?</title>
+<para>
+Marshals are functions which all have the same prototype:
+they take a #GtkObject, a #GtkSignalFunc, a #gpointer,
+and an array of argument values.
+The functions are names gtk_marshall_RETURNTYPE__PARAMTYPE1_PARAMTYPE2....
+</para>
+<para>
+They then call a native function: the GtkObject is the first
+parameter passed in. The arguments are passed in the native
+calling convention: chars, shorts, ints, longs may be packed
+on the stack, or tucked in registers: it doesn't matter
+because the same calling convention will be generated
+inside the gtkmarshal code as is expected where you define
+your handlers.
+</para>
+<para>
+So the function named:
+<programlisting>
+gtk_marshal_BOOL__POINTER_INT_INT_UINT(GtkObject*, GtkSignalFunc, gpointer, GtkArg*);
+</programlisting>
+will call the #GtkSignalFunc assuming it was a function with signature:
+<programlisting>
+gboolean sigfunc(gpointer,gint,gint,guint);
+</programlisting>
+</para>
+</refsect2>
+<refsect2>
+<title>Writing Custom Marshals</title>
+<para>
+Marshals are primarily used as arguments to gtk_signal_new().
+Sometimes, you may find that a marshaller you need isn't available
+in the standard list. Then you have to write your own.
+</para>
<para>
+If you wish to define a signal with a new type of argument list.
+Suppose you want 2 pointers and 2 integers.
+You would write:
+<programlisting>
+typedef int (*GtkSignal_INT__POINTER_POINTER_INT_INT)(
+ gpointer, gpointer, gint, gint
+);
+void marshal_INT__POINTER_POINTER_INT_INT(GtkObject* object,
+ GtkSignalFunc func,
+ gpointer func_data,
+ GtkArg* args)
+{
+ GtkSignal_NONE__POINTER_POINTER_INT_INT rfunc;
+ gint* return_val;
+ return_val = GTK_RETLOC_INT(args[4]);
+ rfunc = (GtkSignal_INT__POINTER_POINTER_INT_INT)func;
+ *return_val = (*rfunc)(object,
+ GTK_VALUE_POINTER(args[0]),
+ GTK_VALUE_POINTER(args[1]),
+ GTK_VALUE_INT(args[2]),
+ GTK_VALUE_INT(args[3]),
+ func_data);
+}
+</programlisting>
</para>
+</refsect2>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### FUNCTION gtk_text_mark_deleted ##### -->
+<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:See_Also ##### -->
<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkSignal</term>
+<listitem><para>The signal handling functions (of which marshallers are
+really an implementation detail).</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-@mark:
-@Returns:
-<!-- ##### MACRO gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Short_Description ##### -->
+Functions to adapt C structures to native calling convention.
-</para>
+<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Title ##### -->
+Signal Marshallers
-<!-- ##### SIGNAL GtkEditable::set-editable ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Long_Description ##### -->
<para>
-Determines if the user can edit the text in the editable
-widget or not. This is meant to be overriden by
-child classes and should not generally useful to
-applications.
+
</para>
-@editable: the object which received the signal.
-@is_editable: %TRUE if the user is allowed to edit the text
- in the widget.
-<!-- ##### FUNCTION gtk_model_simple_node_deleted ##### -->
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:See_Also ##### -->
<para>
</para>
-@simple:
-@path:
-@iter:
-<!-- ##### SIGNAL GtkEditable::delete-text ##### -->
-<para>
-This signal is emitted when text is deleted from
-the widget by the user. The default handler for
-this signal will normally be responsible for inserting
-the text, so by connecting to this signal and then
-stopping the signal with gtk_signal_emit_stop(), it
-is possible to modify the inserted text, or prevent
-it from being inserted entirely. The @start_pos
-and @end_pos parameters are interpreted as for
-gtk_editable_delete_text()
-</para>
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Short_Description ##### -->
-@editable: the object which received the signal.
-@start_pos: the starting position.
-@end_pos: the end position.
-<!-- ##### FUNCTION gtk_ruler_draw_ticks ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Title ##### -->
+Menu Factory
+
+
+<!-- ##### SECTION ./tmpl/gtkprivate.sgml:Long_Description ##### -->
<para>
</para>
-@ruler: the gtkruler
-<!-- ##### SIGNAL GtkEditable::kill-line ##### -->
+<!-- ##### SECTION ./tmpl/gtkprivate.sgml:See_Also ##### -->
<para>
-An action signal. Delete a single line.
+
</para>
-@editable: the object which received the signal.
-@direction: the direction in which to delete. Positive
- indicates forward deletion, negative, backwards deletion.
-<!-- ##### FUNCTION gtk_themes_init ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkprivate.sgml:Short_Description ##### -->
-</para>
-@argc:
-@argv:
-<!-- ##### FUNCTION gtk_type_register_enum ##### -->
+<!-- ##### SECTION ./tmpl/gtkprivate.sgml:Title ##### -->
+Private Information
+
+
+<!-- ##### SECTION ./tmpl/gtkrc.sgml:Long_Description ##### -->
<para>
-Register a new set of enum @values and give them the name in
-@type_name.
+GTK+ provides resource file mechanism for configuring
+various aspects of the operation of a GTK+ program
+at runtime.
</para>
-@type_name: must not be null.
-@values: GtkEnumValue*
-@Returns:
+<refsect2><title>Default files</title>
+<para>
+An application can cause GTK+ to parse a specific RC
+file by calling gtk_rc_parse(). In addition to this,
+certain files will be read at the end of gtk_init().
+Unless modified, the files looked for will be <filename>.gtkrc</filename>
+in the users home directory, and
+<filename>$localstatedir/gtk/gtkrc</filename>
+(<literal>$localstatedir</literal> defaults to
+<filename>/usr/local/etc</filename>).
+</para>
+<para>
+The set of these <firstterm>default</firstterm> files
+can be retrieved with gtk_rc_get_default_files()
+and modified with gtk_rc_add_default_file() and
+gtk_rc_set_default_files().
+</para>
+<para>
+For each default file, in addition to the file itself,
+GTK+ will look for a locale-specific file that will
+be parsed in addition to the main file. For instance,
+if <literal>LANG</literal> is set to <literal>ja_JP.ujis</literal>,
+when loading the default file <filename>~/.gtkrc</filename>
+then GTK+ looks for <filename>~/.gtkrc.ja_JP.ujis</filename>,
+<filename>~/.gtkrc.ja_JP</filename>, and
+<filename>~/.gtkrc.ja</filename>, and parses the
+first one it finds.
+</para>
+</refsect2>
-<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Title ##### -->
-Menu Factory
+<refsect2><title>Pathnames and patterns</title>
+<para>
+A resource file defines a number of styles and key bindings and
+attaches them to particular widgets. The attachment is done
+by the <literal>widget</literal>, <literal>widget_class</literal>,
+and <literal>class</literal> declarations. As an example
+of such a statement:
+<programlisting>
+widget "mywindow.*.GtkEntry" style "my-entry-class"
+</programlisting>
+attaches the style <literal>"my-entry-class"</literal>
+to all widgets whose <firstterm>widget class</firstterm>
+matches the <firstterm>pattern</firstterm>
+<literal>"mywindow.*.GtkEntry"</literal>.
+</para>
+<para>
+The patterns here are given in the standard shell glob
+syntax. The <literal>"?"</literal> wildcard matches
+any character, while <literal>"*"</literal> matches
+zero or more of any character. The three types of
+matching are against the widget path, the
+<firstterm>class path</firstterm> and the class
+heirarchy. Both the widget and the class paths consists of a
+<literal>"."</literal> separated list of all the
+parents of the widget and the widget itself from
+outermost to innermost. The difference is that in
+the widget path, the name assigned by
+<function>gtk_widget_set_name()</function> is used
+if present, otherwise the class name of the widget, while
+for the widget path, the class name is always used.
+</para>
+<para>
+So, if you have a <classname>GtkEntry</classname> named
+<literal>"myentry"</literal>, inside of a of a window
+named <literal>"mywindow"</literal>, then the
+widget path is:
+<programlisting>
+"mwindow.GtkHBox.myentry"
+</programlisting>
+while the class path is:
+<programlisting>
+"GtkWindow.GtkHBox.GtkEntry"
+</programlisting>
+</para>
+<para>
+Matching against class is a little different. The pattern
+match is done against all class names in the widgets
+class heirarchy (not the layout heirarchy) in sequence, so the
+pattern:
+<programlisting>
+class "GtkButton" style "my-style"
+</programlisting>
+will match not just <classname>GtkButton</classname> widgets,
+but also <classname>GtkToggleButton</classname> and
+<classname>GtkCheckButton</classname> widgets, since
+those classes derive from <classname>GtkButton</classname>.
+</para>
+</refsect2>
+<refsect2><title>Toplevel declarations</title>
+<para>
+An RC file is a text file which is composed of a sequence
+of declarations. '#' characters delimit comments and
+the portion of a line after a '#' is ignored when parsing
+an RC file.
+</para>
-<!-- ##### VARIABLE gtk_debug_flags ##### -->
<para>
+The possible toplevel declarations are:
+<variablelist>
+ <varlistentry>
+ <term><literal>binding <replaceable>name</replaceable>
+ { ... }</literal></term>
+ <listitem>
+ <para>Declare a binding set</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>class <replaceable>pattern</replaceable>
+ [ style | binding [ : <replaceable>priority</replaceable> ]]
+ <replaceable>name</replaceable></literal></term>
+ <listitem>
+ <para>Specify a style or binding set for a particular
+ branch of the inheritance heirarchy.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>include <replaceable>filename</replaceable></literal></term>
+ <listitem>
+ <para>Parse another file at this point</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>module_path <replaceable>path></replaceable></literal></term>
+ <listitem>
+ <para>Sets a path (a list of directories separated
+ by colons) that will be searched for theme engines referenced in
+ RC files.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>pixmap_path <replaceable>path></replaceable></literal></term>
+ <listitem>
+ <para>Sets a path (a list of directories separated
+ by colons) that will be searched for pixmaps referenced in
+ RC files.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>style <replaceable>name</replaceable> [ =
+ <replaceable>parent</replaceable> ] { ... }</literal></term>
+ <listitem>
+ <para>Declare a style</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>widget <replaceable>pattern</replaceable>
+ [ style | binding [ : <replaceable>priority</replaceable> ]]
+ <replaceable>name</replaceable></literal></term>
+ <listitem>
+ <para>Specify a style or binding set for a particular
+ group of widgets by matching on the widget pathname.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>widget_class <replaceable>pattern</replaceable>
+ [ style | binding [ : <replaceable>priority</replaceable> ]]
+ <replaceable>name</replaceable></literal></term>
+ <listitem>
+ <para>Specify a style or binding set for a particular
+ group of widgets by matching on the class pathname.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
</para>
+</refsect2>
+<refsect2><title>Styles</title>
+<para>
+A RC style is specified by a <literal>style</literal>
+declaration in a RC file, and then bound to widgets
+with a <literal>widget</literal>, <literal>widget_class</literal>,
+or <literal>class</literal> declaration. All styles
+applying to a particular widget are composited together
+with <literal>widget</literal> declarations overriding
+<literal>widget_class</literal> declarations which, in
+turn, override <literal>widget</literal> declarations.
+Within each type of declaration, later declarations override
+earlier ones.
+</para>
-<!-- ##### MACRO gtk_widget_set_visual ##### -->
<para>
+Within a <literal>style</literal> declaration, the possible
+elements are:
+<variablelist>
+ <varlistentry>
+ <term><literal>bg[<replaceable>state</replaceable>] =
+ <replaceable>color</replaceable></literal></term>
+ <listitem>
+ <para>
+ Set color used for the background of most widgets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>fg[<replaceable>state</replaceable>] =
+ <replaceable>color</replaceable></literal></term>
+ <listitem>
+ <para>
+ Set color used for the foreground of most widgets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>base[<replaceable>state</replaceable>] =
+ <replaceable>color</replaceable></literal></term>
+ <listitem>
+ <para>
+ Set color used for the background of widgets displaying
+ editable text. This color is used for the background
+ of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkClist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>text[<replaceable>state</replaceable>] =
+ <replaceable>color</replaceable></literal></term>
+ <listitem>
+ <para>
+ Set color used for foreground of widgets using
+ <literal>base</literal> for the background color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>bg_text[<replaceable>state</replaceable>] =
+ <replaceable>color</replaceable></literal></term>
+ <listitem>
+ <para>
+ Set a background pixmap to be used in place of
+ the <literal>bg</literal> color (or for #GtkText,
+ in place of the <literal>base</literal> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>font = <replaceable>font</replaceable></literal></term>
+ <listitem>
+ <para>
+ Set the font for a widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>fontset = <replaceable>font</replaceable></literal></term>
+ <listitem>
+ <para>
+ Set the fontset for a widget. Overrides any
+ <literal>font</literal> declarations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>stock[<replaceable>"stock-id"</replaceable>] = { <replaceable>icon source specifications</replaceable> }</literal></term>
+ <listitem>
+ <para>
+ Defines the icon for a stock item.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
</para>
+<para>
+The colors and background pixmaps are specified as a function of the
+state of the widget. The states are:
-@w:
-@v:
-@widget:
-@visual:
+<variablelist>
+ <varlistentry>
+ <term><literal>NORMAL</literal></term>
+ <listitem>
+ <para>
+ A color used for a widget in its normal state
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ACTIVE</literal></term>
+ <listitem>
+ <para>
+ A variant of the <literal>NORMAL</literal> color used when the
+ widget is in the %GTK_STATE_ACTIVE state, and also for
+ the trough of a ScrollBar, tabs of a NoteBook
+ other than the current tab and similar areas.
+ Frequently, this should be a darker variant
+ of the <literal>NORMAL</literal> color.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>PRELIGHT</literal></term>
+ <listitem>
+ <para>
+ A color used for widgets in the %GTK_STATE_PRELIGHT state. This
+ state is the used for Buttons and MenuItems
+ that have the mouse cursor over them, and for
+ their children.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>SELECTED</literal></term>
+ <listitem>
+ <para>
+ A color used to highlight data selected by the user.
+ for instance, the selected ListItems in a List widget, and the
+ selection in an Editable widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>INSENSITIVE</literal></term>
+ <listitem>
+ <para>
+ A color used for the background of widgets that have
+ been set insensitive with gtk_widget_set_sensitive()
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
-<!-- ##### FUNCTION gtk_widget_setv ##### -->
<para>
+Colors can be specified as a string <literal>"&hash;rrrrggggbbbb"</literal>,
+<literal>"&hash;rrrgggbbb"</literal>, <literal>"&hash;rrggbb"</literal>,
+or <literal>"&hash;rgb"</literal>, where <literal>r</literal>
+<literal>g</literal>, and <literal>b</literal> are
+hex digits, or they can be specified as a triplet of floats
+<literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,
+<replaceable>b</replaceable>}</literal>.
+</para>
+<para>
+In a <literal>stock</literal> definition, icon sources are specified as a
+4-tuple of image filename, text direction, widget state, and size, in that
+order. Each icon source specifies an image filename to use with a given
+direction, state, and size. The <literal>*</literal> character can be used as a
+wildcard, and if direction/state/size are omitted they default to
+<literal>*</literal>. So for example, the following specifies different icons to
+use for left-to-right and right-to-left languages:
+<programlisting>
+stock["my-stock-item"] =
+{
+ { "itemltr.png", LTR, *, * },
+ { "itemrtl.png", RTL, *, * }
+}
+</programlisting>
+This could be abbreviated as follows:
+<programlisting>
+stock["my-stock-item"] =
+{
+ { "itemltr.png", LTR },
+ { "itemrtl.png", RTL }
+}
+</programlisting>
</para>
-@widget:
-@nargs:
-@args:
+<para>
+You can specify custom icons for specific sizes, as follows:
+<programlisting>
+stock["my-stock-item"] =
+{
+ { "itemmenusize.png", *, *, "gtk-menu" },
+ { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
+ { "itemgeneric.png" } /* implicit *, *, * as a fallback */
+}
+</programlisting>
+The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
+<literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
+<literal>"gtk-button"</literal>, <literal>"gtk-dialog"</literal>. Applications
+can define other sizes.
+</para>
-<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_ENUM_ENUM_POINTER ##### -->
<para>
+It's also possible to use custom icons for a given state, for example:
+You can specify custom icons for specific sizes, as follows:
+<programlisting>
+stock["my-stock-item"] =
+{
+ { "itemprelight.png", *, PRELIGHT },
+ { "iteminsensitive.png", *, INSENSITIVE },
+ { "itemgeneric.png" } /* implicit *, *, * as a fallback */
+}
+</programlisting>
+</para>
+<para>
+When selecting an icon source to use, GTK+ will consider text direction most
+important, state second, and size third. It will select the best match based on
+those criteria. If an attribute matches exactly (e.g. you specified
+<literal>PRELIGHT</literal> or specified the size), GTK+ won't modify the image;
+if the attribute matches with a wildcard, GTK+ will scale or modify the image to
+match the state and size the user requested.
</para>
+</refsect2>
-<!-- ##### MACRO GTK_TYPE_SEQNO ##### -->
+<refsect2><title>Key bindings</title>
<para>
-Convert a gtk type into its sequence number
+Key bindings allow the user to specify actions to be
+taken on particular key presses. The form of a binding
+set declaration is:
</para>
-@type:
+<programlisting>
+binding <replaceable>name</replaceable> {
+ bind <replaceable>key</replaceable> {
+ <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
+ ...
+ }
+ ...
+}
+</programlisting>
-<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:See_Also ##### -->
<para>
-
+<replaceable>key</replaceable> is a string consisting of a
+series of modifiers followed by the name of a key. The
+modifiers can be:
+<simplelist>
+<member><literal><alt></literal></member>
+<member><literal><control></literal></member>
+<member><literal><mod1></literal></member>
+<member><literal><mod2></literal></member>
+<member><literal><mod3></literal></member>
+<member><literal><mod4></literal></member>
+<member><literal><mod5></literal></member>
+<member><literal><release></literal></member>
+<member><literal><shft></literal></member>
+<member><literal><shift></literal></member>
+</simplelist>
+<literal><shft></literal> is an alias for
+<literal><shift></literal> and
+<literal><alt></literal> is an alias for
+<literal><mod1></literal>.
+</para>
+
+<para>
+The action that is bound to the key is a sequence
+of signal names (strings) followed by parameters for
+each signal. The signals must be action signals.
+(See gtk_signal_new()). Each parameter can be
+a float, integer, string, or unquoted string
+representing an enumeration value. The types of
+the parameters specified must match the types of the
+parameters of the signal.
+</para>
+
+<para>
+Binding sets are connected to widgets in the
+same manner as styles, with one addition.
+A priority can be specified for each pattern,
+and within each type of pattern, binding sets
+override other binding sets first by priority,
+and only then by order of specification. (Later
+overrides earlier). The priorities that can
+be specified are (highest to lowest):
+<simplelist>
+<member><literal>HIGHEST</literal></member>
+<member><literal>RC</literal></member>
+<member><literal>APPLICATION</literal></member>
+<member><literal>GTK</literal></member>
+<member><literal>LOWEST</literal></member>
+</simplelist>
+<literal>RC</literal> is the default for bindings
+read from an RC file, <literal>APPLICATION</literal>
+should be used for bindings an application sets
+up, and <literal>GTK</literal> is used for bindings
+that GTK+ creates internally.
</para>
+</refsect2>
-<!-- ##### ENUM GtkMenuFactoryType ##### -->
+<!-- ##### SECTION ./tmpl/gtkrc.sgml:See_Also ##### -->
<para>
</para>
-@GTK_MENU_FACTORY_MENU:
-@GTK_MENU_FACTORY_MENU_BAR:
-@GTK_MENU_FACTORY_OPTION_MENU:
-<!-- ##### MACRO gtk_marshal_NONE__STRING ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkrc.sgml:Short_Description ##### -->
+Routines for handling resource files
-</para>
+<!-- ##### SECTION ./tmpl/gtkrc.sgml:Title ##### -->
+Resource Files
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_POINTER_UINT_UINT ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkselection.sgml:Long_Description ##### -->
+
+<para>
+The selection mechanism provides the basis for different types
+of IPC between processes. In particular, drag and drop and
+#GtkClipboard work via selections. You will very seldom or
+never need to use most of the functions in this section directly;
+#GtkClipboard provides a nicer interface to the same functionality.
+</para>
+<para>
+Some of the datatypes defined this section are used in
+the #GtkClipboard and drag-and-drop API's as well. The
+#GtkTargetEntry structure and #GtkTargetList objects represent
+lists of data types that are supported when sending or
+receiving data. The #GtkSelectionData object is used to
+store a chunk of data along with the data type and other
+associated information.
</para>
-<!-- ##### MACRO GTK_WIDGET_IS_OFFSCREEN ##### -->
+<!-- ##### SECTION ./tmpl/gtkselection.sgml:See_Also ##### -->
<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkWidget</term>
+<listitem><para>Much of the operation of selections happens via
+ signals for #GtkWidget. In particular, if you are
+ using the functions in this section, you may need
+ to pay attention to ::selection_get,
+ ::selection_received, and :selection_clear_event
+ signals.</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
-@obj:
-<!-- ##### MACRO GTK_MAX_COMPOSE_LEN ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkselection.sgml:Short_Description ##### -->
+Functions for handling inter-process communication via selections.
-</para>
+<!-- ##### SECTION ./tmpl/gtkselection.sgml:Title ##### -->
+Selections
-<!-- ##### FUNCTION gtk_text_iter_prev_char ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtksignal.sgml:Long_Description ##### -->
+<refsect2>
+<title>What are signals?</title>
+<para>
+Signals are a way to get notification when something happens
+and to customize object behavior according to the
+user's needs.
+Every <WordAsWord>signal</WordAsWord> is uniquely identified by a name,
+"class_name::signal_name", where signal_name might be something like
+"clicked" and class_name might be "GtkButton". Note that some other class
+may also define a "clicked" callback, so long as it doesn't derive from
+#GtkButton.
+</para>
+<para>
+When they are created, they are also assigned a unique positive integer,
+the signal id (1 is the first signal id- 0 is used to flag an error).
+Each is also tied to an array of types that describes
+the prototype of the function pointer(s) (handlers) you may
+connect to the signal. Finally, every signal has
+a default handler that is given by a function pointer
+in its class structure: it is run by default whenever the
+signal is emitted. (It is possible that a signal will
+be emitted and a user-defined handler will prevent the default handler
+from being run.)
+</para>
+<para>
+Signals are used by everyone, but they are only
+created on a per class basis-- so you should call
+call gtk_signal_new() unless you are writing
+a new #GtkObject type. However, if you want to make a new signal
+for an existing type, you may use gtk_object_class_user_signal_new()
+to create a signal that doesn't correspond to a class's builtin
+methods.
+</para>
+</refsect2>
+<refsect2>
+<title>How are signals used?</title>
+<para>
+There are two basic actions in the signal handling game.
+If you want notification of an event, you must <Emphasis>connect</Emphasis>
+a function pointer and a data pointer to that signal; the data pointer
+will be passed as the last argument to the function (so long as you
+are using the default marshalling functions).
+You will receive a connection id, a unique positive integer
+corresponding to that attachment.
+</para>
+<para>
+Functions that want to notify the user of certain actions,
+<Emphasis>emit</Emphasis> signals.
</para>
+</refsect2>
+<refsect2>
+<title>Basic Terminology</title>
+<variablelist>
-@iter:
-@Returns:
+<varlistentry>
+<term>signal</term>
+<listitem><para>A class method, e.g. GtkButton::clicked.
+More precisely it is a unique class-branch/signal-name pair.
+This means you may not define a signal handler for a class which
+derives from GtkButton that is called clicked,
+but it is okay to share signals names if they are separate in
+the class tree.
+</para></listitem>
+</varlistentry>
-<!-- ##### SECTION ./tmpl/gtkprivate.sgml:Short_Description ##### -->
+<varlistentry>
+<term>default handler</term>
+<listitem><para>The object's internal method which is invoked
+when the signal is emitted.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>user-defined handler</term>
+<listitem><para>A function pointer and data connected
+to a signal (for a particular object).</para>
+<para>There are really two types: those which are connected
+normally, and those which are connected by one
+of the connect_after functions. The connect_after handlers
+are always run after the default handler.</para>
+<para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>emission</term>
+<listitem><para>the whole process of emitting a signal,
+including the invocation of all
+the different handler types mentioned above.</para>
+</listitem>
+</varlistentry>
-<!-- ##### SIGNAL GtkTextView::cut-text ##### -->
-<para>
+<varlistentry>
+<term>signal id</term>
+<listitem><para>The unique positive (nonzero) integer
+used to identify a signal. It can be used instead of
+a name to many functions for a slight performance
+improvement.</para>
+</listitem>
+</varlistentry>
-</para>
+<varlistentry>
+<term>connection id</term>
+<listitem><para>The unique positive (nonzero) integer
+used to identify the connection of a user-defined handler
+to a signal. Notice that it is allowed to connect the
+same function-pointer/user-data pair twice, so
+there is no guarantee that a function-pointer/user-data
+maps to a unique connection id.
+</para>
+</listitem>
+</varlistentry>
-@textview: the object which received the signal.
+</variablelist>
+</refsect2>
-<!-- ##### FUNCTION gtk_theme_engine_unref ##### -->
+<refsect2><title>A brief note on how they work.</title>
<para>
-
+The functions responsible for translating an array of #GtkArgs
+to your C compiler's normal semantics are called Marshallers.
+They are identified by
+gtk_marshal_return_value__parameter_list()
+for example a C function returning a gboolean and taking a gint
+can be invoked by using gtk_marshal_BOOL__INT().
+Not all possibly combinations of return/params are available,
+of course, so if you are writing a #GtkObject with parameters
+you might have to write a marshaller.
</para>
+</refsect2>
-@engine:
-<!-- ##### ARG GtkTextTag:left-wrapped-line-margin-set ##### -->
+<!-- ##### SECTION ./tmpl/gtksignal.sgml:See_Also ##### -->
<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkObject</term>
+<listitem><para>The base class for things which emit signals.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-<!-- ##### STRUCT GtkDialogButton ##### -->
-<para>
-Deprecated.
-</para>
+<!-- ##### SECTION ./tmpl/gtksignal.sgml:Short_Description ##### -->
+Object methods and callbacks.
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER ##### -->
+<!-- ##### SECTION ./tmpl/gtksignal.sgml:Title ##### -->
+Signals
+
+
+<!-- ##### SECTION ./tmpl/gtkstock.sgml:Long_Description ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### FUNCTION gtk_tree_store_getv ##### -->
+<!-- ##### SECTION ./tmpl/gtkstock.sgml:See_Also ##### -->
<para>
</para>
-@tree_store:
-@iter:
-@var_args:
-<!-- ##### FUNCTION gtk_text_buffer_cut ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkstock.sgml:Short_Description ##### -->
-</para>
-@buffer:
-@time:
-@interactive:
-@default_editable:
-<!-- ##### SIGNAL GtkEditable::activate ##### -->
-<para>
-Indicates that the user has activated the widget
-in some fashion. Generally, this will be done
-with a keystroke. (The default binding for this
-action is Return for #GtkEntry and
-Control-Return for #GtkText.)
-</para>
+<!-- ##### SECTION ./tmpl/gtkstock.sgml:Title ##### -->
+Stock Items
-@editable: the object which received the signal.
-<!-- ##### ENUM GtkTextViewMovementStep ##### -->
+<!-- ##### SECTION ./tmpl/gtkstyle.sgml:Long_Description ##### -->
<para>
</para>
-@GTK_TEXT_MOVEMENT_CHAR:
-@GTK_TEXT_MOVEMENT_POSITIONS:
-@GTK_TEXT_MOVEMENT_WORD:
-@GTK_TEXT_MOVEMENT_WRAPPED_LINE:
-@GTK_TEXT_MOVEMENT_LINE:
-@GTK_TEXT_MOVEMENT_LINE_ENDS:
-@GTK_TEXT_MOVEMENT_BUFFER_ENDS:
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_INT_INT ##### -->
+<!-- ##### SECTION ./tmpl/gtkstyle.sgml:See_Also ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### ARG GtkTextTag:left-wrapped-line-margin ##### -->
-<para>
-Pixel width of the left margin of the text for lines after the first
-line in a wrapped paragraph.
-</para>
+<!-- ##### SECTION ./tmpl/gtkstyle.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/gtkdebug.sgml:See_Also ##### -->
-<para>
-</para>
+<!-- ##### SECTION ./tmpl/gtkstyle.sgml:Title ##### -->
+Styles
-<!-- ##### FUNCTION gtk_paint_oval ##### -->
+<!-- ##### SECTION ./tmpl/gtkthemes.sgml:Long_Description ##### -->
<para>
</para>
-@style:
-@window:
-@state_type:
-@shadow_type:
-@area:
-@widget:
-@detail:
-@x:
-@y:
-@width:
-@height:
-<!-- ##### MACRO GTK_CONTAINER_RESIZE_PENDING ##### -->
+<!-- ##### SECTION ./tmpl/gtkthemes.sgml:See_Also ##### -->
<para>
</para>
-@obj:
-<!-- ##### SIGNAL GtkEditable::copy-clipboard ##### -->
-<para>
-An action signal. Causes the characters in the current selection to
-be copied to the clipboard.
-</para>
+<!-- ##### SECTION ./tmpl/gtkthemes.sgml:Short_Description ##### -->
-@editable: the object which received the signal.
-<!-- ##### FUNCTION gtk_clist_construct ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkthemes.sgml:Title ##### -->
+Themes
+
+
+<!-- ##### SECTION ./tmpl/gtktreemodelsimple.sgml:Long_Description ##### -->
<para>
-Initializes a previously allocated #GtkCList widget for use. This should not
-normally be used to create a #GtkCList widget. Use gtk_clist_new() instead.
+
</para>
-@clist: A pointer to an uninitialized #GtkCList widget.
-@columns: The number of columns the #GtkCList should have.
-@titles: An array of strings that should be used as the titles i
-of the columns. There should be enough strings in the array for
-the number of columns specified.
-<!-- ##### FUNCTION gtk_menu_factory_remove_entries ##### -->
+<!-- ##### SECTION ./tmpl/gtktreemodelsimple.sgml:See_Also ##### -->
<para>
</para>
-@factory:
-@entries:
-@nentries:
-<!-- ##### FUNCTION gtk_tree_view_move_to ##### -->
+<!-- ##### SECTION ./tmpl/gtktreemodelsimple.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gtktreemodelsimple.sgml:Title ##### -->
+GtkModelSimple
+
+
+<!-- ##### SECTION ./tmpl/gtktreeview.sgml:Long_Description ##### -->
<para>
</para>
-@tree_view:
-@path:
-@column:
-@row_align:
-@col_align:
-<!-- ##### FUNCTION gtk_text_buffer_find_string ##### -->
+<!-- ##### SECTION ./tmpl/gtktreeview.sgml:See_Also ##### -->
<para>
</para>
-@buffer:
-@iter:
-@str:
-@start:
-@end:
-@Returns:
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT_POINTER ##### -->
-<para>
-</para>
+<!-- ##### SECTION ./tmpl/gtktreeview.sgml:Short_Description ##### -->
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### FUNCTION gtk_marshal_INT__INT ##### -->
-<para>
-</para>
+<!-- ##### SECTION ./tmpl/gtktreeview.sgml:Title ##### -->
+GtkTreeView
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT_BOOL ##### -->
+<!-- ##### SECTION ./tmpl/gtktypeutils.sgml:Long_Description ##### -->
<para>
-
+Gtk's type system is extensible. Because of that, types have to be
+managed at runtime.
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### FUNCTION gtk_paned_compute_position ##### -->
+<!-- ##### SECTION ./tmpl/gtktypeutils.sgml:See_Also ##### -->
<para>
-Internal function used by #GtkHPaned and #GtkVPaned
+
</para>
-@paned:
-@allocation:
-@child1_req:
-@child2_req:
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_STRING_STRING ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtktypeutils.sgml:Short_Description ##### -->
+Handle run-time type creation.
-</para>
+<!-- ##### SECTION ./tmpl/gtktypeutils.sgml:Title ##### -->
+Types
-<!-- ##### FUNCTION gtk_trace_referencing ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkvbbox.sgml:Long_Description ##### -->
<para>
-Private: print debugging information while doing a gtk_object_ref() or
-a gtk_object_unref().
+A button box should be used to provide a consistent layout of buttons
+throughout your application. There is one default layout and a default
+spacing value that are persistant across all #VButtonBox widgets.
+</para>
+<para>
+The layout/spacing can then be altered by the programmer, or if desired, by
+the user to alter the 'feel' of a program to a small degree.
+</para>
+<para>
+A #VButtonBox is created with gtk_vbutton_box_new(). Buttons are packed into
+a button box the same way as any other box, using gtk_box_pack_start() or
+gtk_box_pack_end().
+</para>
+<para>
+The default spacing between buttons can be set with
+gtk_vbutton_box_set_spacing_default() and queried with
+gtk_vbutton_box_get_spacing_default().
+</para>
+<para>
+The arrangement and layout of the buttons can be changed using
+gtk_vbutton_box_set_layout_default() and queried with
+gtk_vbutton_box_get_layout_default().
</para>
-@object: object to reference or unreference.
-@func: name of caller's function to print (used within macros).
-@dummy: unused.
-@line: line number (used within macros).
-@do_ref: whether to reference or unreference.
-<!-- ##### MACRO GTK_VALUE_CALLBACK ##### -->
+<!-- ##### SECTION ./tmpl/gtkvbbox.sgml:See_Also ##### -->
<para>
-Use to get the value of a GtkArg whose GtkType is GTK_TYPE_CALLBACK
+<variablelist>
+<varlistentry>
+<term>#GtkBox</term>
+<listitem><para>Used to pack widgets into button boxes.</para></listitem>
+</varlistentry><varlistentry>
+<term>#GtkButtonBox</term>
+<listitem><para>Provides functions for controlling button boxes.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>#GtkHButtonBox</term>
+<listitem><para>Pack buttons horizontally.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-@a:
-<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT_BOOL ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkvbbox.sgml:Short_Description ##### -->
+a container for arranging buttons vertically.
-</para>
+<!-- ##### SECTION ./tmpl/gtkvbbox.sgml:Title ##### -->
+GtkVButtonBox
-<!-- ##### FUNCTION gtk_object_args_collect ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkvbox.sgml:Long_Description ##### -->
<para>
-Private: Gets an array of #GtkArgs from a va_list C structure.
+GtkVBox is a container that organizes child widgets into a single column.
</para>
-@object_type: the type of object to collect arguments for.
-@arg_list_p: pointer to be filled in with a list of parsed arguments.
-@info_list_p: optional pointer for a returned list #GtkArgInfos.
-@first_arg_name: name of first argument.
-@var_args: value of first argument, followed by more key/value pairs,
-terminated by NULL.
-@Returns: an error message, or NULL on success.
-It is the caller's responsibility to call g_free() in the event of error.
-
-<!-- ##### ENUM GtkFontType ##### -->
<para>
-A set of bit flags used to specify the type of fonts shown
-when calling gtk_font_selection_dialog_set_filter() or
-gtk_font_selection_set_filter().
+Use the #GtkBox packing interface to determine the arrangement,
+spacing, height, and alignment of GtkVBox children.
</para>
-@GTK_FONT_BITMAP: bitmap fonts.
-@GTK_FONT_SCALABLE: scalable fonts.
-@GTK_FONT_SCALABLE_BITMAP: scaled bitmap fonts.
-@GTK_FONT_ALL: a bitwise combination of all of the above.
-
-<!-- ##### MACRO GTK_TYPE_STRUCTURED_LAST ##### -->
<para>
-The last structured enumerated type value.
+All children are allocated the same width.
</para>
-<!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->
+<!-- ##### SECTION ./tmpl/gtkvbox.sgml:See_Also ##### -->
<para>
-Get the number of signals defined by this object.
-</para>
+<variablelist>
-@obj: the object to query.
+<varlistentry>
+<term>#GtkHBox</term>
+<listitem><para>a sister class that organizes widgets into a row.</para></listitem>
+</varlistentry>
-<!-- ##### FUNCTION gtk_object_arg_get ##### -->
-<para>
-Private function to get an argument and argument info from an object.
+</variablelist>
</para>
-@object: the object whose argument should be retrieved.
-@arg: the argument, for the name on input, the rest is filled on output.
-@info: a #GtkArgInfo structure to optionally fill in.
-<!-- ##### FUNCTION gtk_menu_factory_remove_subfactory ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkvbox.sgml:Short_Description ##### -->
+vertical container box
-</para>
-@factory:
-@subfactory:
-@path:
+<!-- ##### SECTION ./tmpl/gtkvbox.sgml:Title ##### -->
+GtkVBox
-<!-- ##### FUNCTION gtk_type_children_types ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkviewport.sgml:Long_Description ##### -->
<para>
-Return the pointer to the type's children's types.
+
</para>
-@type: GtkType
-@Returns: pointer to a GList
-<!-- ##### SIGNAL GtkEditable::move-page ##### -->
+<!-- ##### SECTION ./tmpl/gtkviewport.sgml:See_Also ##### -->
<para>
-An action signal. Move the cursor by pages.
+
</para>
-@editable: the object which received the signal.
-@x: Number of pages to move the cursor horizontally.
-@y: Number of pages to move the cursor vertically.
-<!-- ##### FUNCTION gtk_type_register_flags ##### -->
+<!-- ##### SECTION ./tmpl/gtkviewport.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gtkviewport.sgml:Title ##### -->
+GtkViewport
+
+
+<!-- ##### SECTION ./tmpl/gtkvpaned.sgml:Long_Description ##### -->
<para>
-Register a new set of flags @values and give them the name in
-@type_name.
+The VPaned widget is a container widget with two
+children arranged vertically. The division between
+the two panes is adjustable by the user by dragging
+a handle. See #GtkPaned for details.
</para>
-@type_name: must not be null.
-@values: GtkFlagValue*
-@Returns:
-<!-- ##### SIGNAL GtkTextView::scroll-text ##### -->
+<!-- ##### SECTION ./tmpl/gtkvpaned.sgml:See_Also ##### -->
<para>
</para>
-@textview: the object which received the signal.
-@arg1:
-<!-- ##### ENUM GtkPrivateFlags ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkvpaned.sgml:Short_Description ##### -->
+A container with two panes arranged vertically.
-</para>
-@PRIVATE_GTK_USER_STYLE:
-@PRIVATE_GTK_RESIZE_PENDING:
-@PRIVATE_GTK_RESIZE_NEEDED:
-@PRIVATE_GTK_LEAVE_PENDING:
-@PRIVATE_GTK_HAS_SHAPE_MASK:
-@PRIVATE_GTK_IN_REPARENT:
-@PRIVATE_GTK_DIRECTION_SET:
-@PRIVATE_GTK_DIRECTION_LTR:
+<!-- ##### SECTION ./tmpl/gtkvpaned.sgml:Title ##### -->
+GtkVPaned
-<!-- ##### FUNCTION gtk_type_set_chunk_alloc ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkvruler.sgml:Long_Description ##### -->
<para>
-Set the mem_chunk size so it will hold @n_chunks of the objects of that @type.
+ NOTE this widget is considered too specialized/little-used for
+ GTK+, and will in the future be moved to some other package. If
+ your application needs this widget, feel free to use it, as the
+ widget does work and is useful in some applications; it's just not
+ of general interest. However, we are not accepting new features for
+ the widget, and it will eventually move out of the GTK+
+ distribution.
+</para>
+<para>
+The VRuler widget is a widget arranged vertically creating a ruler that is
+utilized around other widgets such as a text widget. The ruler is used to show
+the location of the mouse on the window and to show the size of the window in
+specified units. The available units of measurement are GTK_PIXELS, GTK_INCHES
+and GTK_CENTIMETERS. GTK_PIXELS is the default.
+rulers.
</para>
-@type: There must be an unlocked TypeNode associated with this type otherwise nothing happens.
-@n_chunks:
-<!-- ##### FUNCTION gtk_draw_oval ##### -->
+<!-- ##### SECTION ./tmpl/gtkvruler.sgml:See_Also ##### -->
<para>
</para>
-@style:
-@window:
-@state_type:
-@shadow_type:
-@x:
-@y:
-@width:
-@height:
-<!-- ##### MACRO GTK_TYPE_STRUCTURED_FIRST ##### -->
+<!-- ##### SECTION ./tmpl/gtkvruler.sgml:Short_Description ##### -->
+A vertical ruler.
+
+
+<!-- ##### SECTION ./tmpl/gtkvruler.sgml:Title ##### -->
+GtkVRuler
+
+
+<!-- ##### SECTION ./tmpl/gtkvscale.sgml:Long_Description ##### -->
<para>
-The first structured enumerated type value.
+The #GtkVScale widget is used to allow the user to select a value using
+a vertical slider.
+A #GtkAdjustment is used to set the initial value, the lower
+and upper bounds, and the step and page increments.
+</para>
+<para>
+The position to show the current value, and the number of decimal places
+shown can be set using the parent #GtkScale class's functions.
</para>
-<!-- ##### STRUCT GtkSignalQuery ##### -->
+<!-- ##### SECTION ./tmpl/gtkvscale.sgml:See_Also ##### -->
<para>
-This structure contains all the information about a particular
-signal: its name, the type it affects, the signature of the handlers,
-and its unique identifying integer.
+
</para>
-@object_type:
-@signal_id:
-@signal_name:
-@is_user_signal:
-@signal_flags:
-@return_val:
-@nparams:
-@params:
-<!-- ##### FUNCTION gtk_type_describe_tree ##### -->
+<!-- ##### SECTION ./tmpl/gtkvscale.sgml:Short_Description ##### -->
+a vertical slider widget for selecting a value from a range.
+
+
+<!-- ##### SECTION ./tmpl/gtkvscale.sgml:Title ##### -->
+GtkVScale
+
+
+<!-- ##### SECTION ./tmpl/gtkvscrollbar.sgml:Long_Description ##### -->
<para>
-Given a @type, describe all of its children, and their children. Only
-show the size if @show_size is true.
+The VScrollbar widget is a widget arranged vertically creating a scroll bar. See
+#GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be added to
+handle the adjustment of the scrollbars or it may be left NULL in which case one
+will be created you. See #GtkAdjustment for details.
</para>
-@type: GtkType
-@show_size: gboolean
-<!-- ##### FUNCTION gtk_text_mark_is_visible ##### -->
+<!-- ##### SECTION ./tmpl/gtkvscrollbar.sgml:See_Also ##### -->
<para>
</para>
-@mark:
-@Returns:
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT_INT ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkvscrollbar.sgml:Short_Description ##### -->
+A vertical scrollbar
-</para>
-@object:
-@func:
-@func_data:
-@args:
+<!-- ##### SECTION ./tmpl/gtkvscrollbar.sgml:Title ##### -->
+GtkVScrollbar
-<!-- ##### SIGNAL GtkEditable::kill-char ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkvseparator.sgml:Long_Description ##### -->
<para>
-An action signal. Delete a single character.
+The #GtkVSeparator widget is a vertical separator, used to group the
+widgets within a window. It displays a vertical line with a shadow to
+make it appear sunken into the interface.
</para>
-@editable: the object which received the signal.
-@direction: the direction in which to delete. Positive
- indicates forward deletion, negative, backwards deletion.
-<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/gtkvseparator.sgml:See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkHSeparator</term>
+<listitem><para>a horizontal separator.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-<!-- ##### FUNCTION gtk_window_remove_embedded_xid ##### -->
-<para>
+<!-- ##### SECTION ./tmpl/gtkvseparator.sgml:Short_Description ##### -->
+a vertical separator.
-</para>
-@window:
-@xid:
+<!-- ##### SECTION ./tmpl/gtkvseparator.sgml:Title ##### -->
+GtkVSeparator
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT ##### -->
+
+<!-- ##### SECTION ./tmpl/gtkwidget.sgml:Long_Description ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### FUNCTION gtk_text_iter_get_pixmap ##### -->
+<!-- ##### SECTION ./tmpl/gtkwidget.sgml:See_Also ##### -->
<para>
</para>
-@iter:
-@pixmap:
-@mask:
-@Returns:
-<!-- ##### SIGNAL GtkEditable::kill-word ##### -->
-<para>
-An action signal. Delete a single word.
-</para>
+<!-- ##### SECTION ./tmpl/gtkwidget.sgml:Short_Description ##### -->
-@editable: the object which received the signal.
-@direction: the direction in which to delete. Positive
- indicates forward deletion, negative, backwards deletion.
-<!-- ##### FUNCTION gtk_im_context_simple_add_table ##### -->
-<para>
-</para>
+<!-- ##### SECTION ./tmpl/gtkwidget.sgml:Title ##### -->
+GtkWidget
-@context_simple:
-@data:
-@max_seq_len:
-@n_seqs:
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_UINT ##### -->
+<!-- ##### SECTION ./tmpl/gtkwindow.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->
+<!-- ##### SECTION ./tmpl/gtkwindow.sgml:See_Also ##### -->
<para>
-Test whether a GtkObject's arguments have been prepared.
+
</para>
-@obj: the object to examine.
-<!-- ##### FUNCTION gtk_font_selection_dialog_set_filter ##### -->
+<!-- ##### SECTION ./tmpl/gtkwindow.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gtkwindow.sgml:Title ##### -->
+GtkWindow
+
+
+<!-- ##### MACRO GTK_CLIST_CHILD_HAS_FOCUS ##### -->
<para>
-Sets one of the two font filters, to limit the fonts shown.
+A macro to check whether a child widget of the CList
+has the focus.
</para>
-@fsd: a #GtkFontSelectionDialog.
-@filter_type: which of the two font filters to set, either
-#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter
-can be changed by the user, but the base filter is permanent.
-@font_type: the types of font to be shown. This is a bitwise combination of
-#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP,
-or #GTK_FONT_ALL to show all three font types.
-@foundries: a NULL-terminated array of strings containing foundry names which
-will be shown, or NULL to show all foundries.
-@weights: a NULL-terminated array of strings containing weight names which
-will be shown, or NULL to show all weights.
-@slants: a NULL-terminated array of strings containing slant names which
-will be shown, or NULL to show all slants.
-@setwidths: a NULL-terminated array of strings containing setwidth names which
-will be shown, or NULL to show all setwidths.
-@spacings: a NULL-terminated array of strings containing spacings which
-will be shown, or NULL to show all spacings.
-@charsets: a NULL-terminated array of strings containing charset names which
-will be shown, or NULL to show all charsets.
+@clist: The #GtkCList widget to check.
-<!-- ##### SIGNAL GtkTextView::delete-text ##### -->
+<!-- ##### MACRO GTK_CONTAINER_RESIZE_PENDING ##### -->
<para>
</para>
-@textview: the object which received the signal.
-@arg1:
-@arg2:
+@obj:
-<!-- ##### FUNCTION gtk_container_get_toplevels ##### -->
+<!-- ##### MACRO GTK_MAX_COMPOSE_LEN ##### -->
<para>
</para>
-@Returns:
-<!-- ##### MACRO GTK_TYPE_NUM_BUILTINS ##### -->
+<!-- ##### MACRO GTK_NOTE ##### -->
<para>
-No idea.
+
</para>
+@type:
+@action:
-<!-- ##### MACRO GTK_TYPE_MAKE ##### -->
+<!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->
<para>
-Combine a fundemantal type and a sequence number to create a gtk type.
+Test whether a GtkObject's arguments have been prepared.
</para>
-@parent_t:
-@seqno:
+@obj: the object to examine.
-<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Short_Description ##### -->
-Functions to adapt C structures to native calling convention.
+<!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->
+<para>
+Get the number of signals defined by this object.
+</para>
+@obj: the object to query.
-<!-- ##### MACRO GTK_TYPE_FLAT_LAST ##### -->
+<!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->
<para>
-The last "flat" (no struct) enumerated type value.
+Get the array of signals defined for this object.
</para>
+@obj: the object to fetch the signals from.
-<!-- ##### FUNCTION gtk_tree_selection_set_tree_view ##### -->
+<!-- ##### MACRO GTK_PRIVATE_FLAGS ##### -->
<para>
</para>
-@selection:
-@tree_view:
+@wid:
-<!-- ##### FUNCTION gtk_text_mark_unref ##### -->
+<!-- ##### MACRO GTK_PRIVATE_SET_FLAG ##### -->
<para>
</para>
-@mark:
+@wid:
+@flag:
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER ##### -->
+<!-- ##### MACRO GTK_PRIVATE_UNSET_FLAG ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@wid:
+@flag:
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_POINTER ##### -->
+<!-- ##### MACRO GTK_TREE_SELECTION ##### -->
<para>
-
+A macro that returns a GList that contains the selection of the root tree of @obj.
</para>
-@object:
-@func:
-@func_data:
-@args:
+@obj: A pointer to the #GtkTree. @obj will accept any pointer, but it the pointer does not point to a #GtkTree, the results are undefined.
-<!-- ##### FUNCTION gtk_signal_handlers_destroy ##### -->
+<!-- ##### MACRO GTK_TYPE_FLAT_FIRST ##### -->
<para>
-Destroy all the signal handlers connected to an object.
-This is done automatically when the object is destroyed.
+The first "flat" (no struct) enumerated type value.
</para>
+
+
+<!-- ##### MACRO GTK_TYPE_FLAT_LAST ##### -->
<para>
-This function is labeled private.
+The last "flat" (no struct) enumerated type value.
</para>
-@object: the object whose signal handlers should be destroyed.
-<!-- ##### FUNCTION gtk_text_iter_in_region ##### -->
+<!-- ##### MACRO GTK_TYPE_IDENTIFIER ##### -->
<para>
-
+Hide the name of gtk_identifier_get_type
</para>
-@iter:
-@start:
-@end:
-@Returns:
-<!-- ##### FUNCTION gtk_type_get_varargs_type ##### -->
+<!-- ##### MACRO GTK_TYPE_MAKE ##### -->
<para>
-Get the varargs type associated with @foreign_type
+Combine a fundemantal type and a sequence number to create a gtk type.
</para>
-@foreign_type: GtkType
-@Returns: GtkType
+@parent_t:
+@seqno:
-<!-- ##### SIGNAL GtkEditable::changed ##### -->
+<!-- ##### MACRO GTK_TYPE_NUM_BUILTINS ##### -->
<para>
-Indicates that the user has changed the contents
-of the widget.
+No idea.
</para>
-@editable: the object which received the signal.
-<!-- ##### FUNCTION gtk_tree_view_column_get_size ##### -->
+<!-- ##### MACRO GTK_TYPE_SEQNO ##### -->
<para>
+Convert a gtk type into its sequence number
+</para>
+
+@type:
+<!-- ##### MACRO GTK_TYPE_STRUCTURED_FIRST ##### -->
+<para>
+The first structured enumerated type value.
</para>
-@tree_column:
-@Returns:
-<!-- ##### STRUCT GtkMenuFactory ##### -->
+<!-- ##### MACRO GTK_TYPE_STRUCTURED_LAST ##### -->
<para>
+The last structured enumerated type value.
+</para>
+
+<!-- ##### MACRO GTK_VALUE_ARGS ##### -->
+<para>
+Use to get the value of a GtkArg whose GtkType is GTK_TYPE_ARGS
</para>
-@path:
-@type:
-@accel_group:
-@widget:
-@subfactories:
+@a:
-<!-- ##### SIGNAL GtkTextView::delete-at-cursor ##### -->
+<!-- ##### MACRO GTK_VALUE_CALLBACK ##### -->
<para>
+Use to get the value of a GtkArg whose GtkType is GTK_TYPE_CALLBACK
+</para>
+@a:
+
+<!-- ##### MACRO GTK_VALUE_C_CALLBACK ##### -->
+<para>
+Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK
</para>
-@textview: the object which received the signal.
-@arg1:
-@arg2:
+@a:
<!-- ##### MACRO GTK_VALUE_FOREIGN ##### -->
<para>
@a:
-<!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->
+<!-- ##### MACRO GTK_WIDGET_HAS_SHAPE_MASK ##### -->
<para>
-Define a signal-handler for a new signal on an already defined
-object.
+
</para>
+
+@obj:
+
+<!-- ##### MACRO GTK_WIDGET_IN_REPARENT ##### -->
<para>
-See the signal documentation for more general information.
+
</para>
-@klass: the object class to define the signal for.
-@name: the name of the signal.
-@signal_flags: the default emission behavior for the signal.
-See gtk_signal_new().
-@marshaller: a function that will take an array of GtkArgs
-and invoke the appropriate handler with the normal calling
-conventions.
-@return_val: specify the return-value type for the signal
-(or GTK_TYPE_NONE for no return-value).
-@nparams: specify the number of parameters the signal
-receives from the caller of gtk_signal_emit().
-@Varargs: list of nparams #GtkTypes to pass to the signal handlers.
-@Returns: the signal id. (See #GtkSignals)
+@obj:
-<!-- ##### SIGNAL GtkTextView::paste-text ##### -->
+<!-- ##### MACRO GTK_WIDGET_IS_OFFSCREEN ##### -->
<para>
</para>
-@textview: the object which received the signal.
+@obj:
-<!-- ##### MACRO GTK_PRIVATE_SET_FLAG ##### -->
+<!-- ##### MACRO GTK_WIDGET_LEAVE_PENDING ##### -->
<para>
</para>
-@wid:
-@flag:
+@obj:
-<!-- ##### FUNCTION gtk_ruler_draw_pos ##### -->
+<!-- ##### MACRO GTK_WIDGET_REDRAW_PENDING ##### -->
<para>
</para>
-@ruler: the gtkruler
+@obj:
-<!-- ##### FUNCTION gtk_object_newv ##### -->
+<!-- ##### MACRO GTK_WIDGET_RESIZE_NEEDED ##### -->
<para>
-Construct an object with an array of arguments.
+
</para>
-@object_type: the type of the object to create.
-@n_args: the number of arguments to set.
-@args: an array of n_args arguments (which are name and value pairs).
-@Returns: the new GtkObject.
+@obj:
<!-- ##### MACRO GTK_WIDGET_USER_STYLE ##### -->
<para>
@obj:
-<!-- ##### FUNCTION gtk_text_iter_forward_to_newline ##### -->
+<!-- ##### ENUM GtkCellRendererType ##### -->
<para>
</para>
-@iter:
-@Returns:
+@GTK_CELL_RENDERER_SELECTED:
+@GTK_CELL_RENDERER_PRELIT:
+@GTK_CELL_RENDERER_INSENSITIVE:
<!-- ##### ENUM GtkDebugFlag ##### -->
<para>
@GTK_DEBUG_DND:
@GTK_DEBUG_PLUGSOCKET:
-<!-- ##### FUNCTION gtk_menu_factory_remove_paths ##### -->
+<!-- ##### STRUCT GtkDialogButton ##### -->
<para>
-
+Deprecated.
</para>
-@factory:
-@paths:
-@npaths:
-<!-- ##### FUNCTION gtk_type_query ##### -->
+<!-- ##### SIGNAL GtkEditable::activate ##### -->
<para>
-Given a type, return various interesting parameters of the type.
+Indicates that the user has activated the widget
+in some fashion. Generally, this will be done
+with a keystroke. (The default binding for this
+action is Return for #GtkEntry and
+Control-Return for #GtkText.)
</para>
-@type: GtkType
-@Returns: GtkTypeQuery*
+@editable: the object which received the signal.
-<!-- ##### ENUM GtkTreeViewColumnType ##### -->
+<!-- ##### SIGNAL GtkEditable::changed ##### -->
<para>
-
+Indicates that the user has changed the contents
+of the widget.
</para>
-@GTK_TREE_VIEW_COLUMN_RESIZEABLE:
-@GTK_TREE_VIEW_COLUMN_AUTOSIZE:
-@GTK_TREE_VIEW_COLUMN_FIXED:
+@editable: the object which received the signal.
-<!-- ##### SECTION ./tmpl/gtkprivate.sgml:Long_Description ##### -->
+<!-- ##### SIGNAL GtkEditable::copy-clipboard ##### -->
<para>
-
+An action signal. Causes the characters in the current selection to
+be copied to the clipboard.
</para>
+@editable: the object which received the signal.
-<!-- ##### MACRO GTK_TYPE_IDENTIFIER ##### -->
+<!-- ##### SIGNAL GtkEditable::cut-clipboard ##### -->
<para>
-Hide the name of gtk_identifier_get_type
+An action signal. Causes the characters in the current
+selection to be copied to the clipboard and then deleted from
+the widget.
</para>
+@editable: the object which received the signal.
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT ##### -->
+<!-- ##### SIGNAL GtkEditable::delete-text ##### -->
<para>
-
+This signal is emitted when text is deleted from
+the widget by the user. The default handler for
+this signal will normally be responsible for inserting
+the text, so by connecting to this signal and then
+stopping the signal with gtk_signal_emit_stop(), it
+is possible to modify the inserted text, or prevent
+it from being inserted entirely. The @start_pos
+and @end_pos parameters are interpreted as for
+gtk_editable_delete_text()
</para>
-@object:
-@func:
-@func_data:
-@args:
+@editable: the object which received the signal.
+@start_pos: the starting position.
+@end_pos: the end position.
-<!-- ##### MACRO gtk_marshal_NONE__ENUM ##### -->
+<!-- ##### SIGNAL GtkEditable::insert-text ##### -->
<para>
-
+This signal is emitted when text is inserted into
+the widget by the user. The default handler for
+this signal will normally be responsible for inserting
+the text, so by connecting to this signal and then
+stopping the signal with gtk_signal_emit_stop(), it
+is possible to modify the inserted text, or prevent
+it from being inserted entirely.
</para>
+@editable: the object which received the signal.
+@new_text: the new text to insert.
+@new_text_length: the length of the new text.
+@position: the position at which to insert the new text.
+ this is an in-out paramter. After the signal
+ emission is finished, it should point after
+ the newly inserted text.
-<!-- ##### FUNCTION gtk_ctree_construct ##### -->
+<!-- ##### SIGNAL GtkEditable::kill-char ##### -->
<para>
-This function is not usually used by users.
+An action signal. Delete a single character.
</para>
-@ctree:
-@columns:
-@tree_column:
-@titles:
+@editable: the object which received the signal.
+@direction: the direction in which to delete. Positive
+ indicates forward deletion, negative, backwards deletion.
-<!-- ##### FUNCTION gtk_draw_cross ##### -->
+<!-- ##### SIGNAL GtkEditable::kill-line ##### -->
<para>
-
+An action signal. Delete a single line.
</para>
-@style:
-@window:
-@state_type:
-@shadow_type:
-@x:
-@y:
-@width:
-@height:
+@editable: the object which received the signal.
+@direction: the direction in which to delete. Positive
+ indicates forward deletion, negative, backwards deletion.
-<!-- ##### FUNCTION gtk_signal_handler_pending_by_id ##### -->
+<!-- ##### SIGNAL GtkEditable::kill-word ##### -->
<para>
-Returns whether a connection id is valid (and optionally not blocked).
+An action signal. Delete a single word.
</para>
-@object: the object to search for the desired handler.
-@handler_id: the connection id.
-@may_be_blocked: whether it is acceptable to return a blocked
-handler.
-@Returns: TRUE if the signal exists and wasn't blocked,
-unless #may_be_blocked was specified. FALSE otherwise.
+@editable: the object which received the signal.
+@direction: the direction in which to delete. Positive
+ indicates forward deletion, negative, backwards deletion.
-<!-- ##### FUNCTION gtk_tree_selection_new ##### -->
+<!-- ##### SIGNAL GtkEditable::move-cursor ##### -->
<para>
-
+An action signal. Move the cursor position.
</para>
-@Returns:
+@editable: the object which received the signal.
+@x: horizontal distance to move the cursor.
+@y: vertical distance to move the cursor.
-<!-- ##### MACRO GTK_PRIVATE_FLAGS ##### -->
+<!-- ##### SIGNAL GtkEditable::move-page ##### -->
<para>
-
+An action signal. Move the cursor by pages.
</para>
-@wid:
+@editable: the object which received the signal.
+@x: Number of pages to move the cursor horizontally.
+@y: Number of pages to move the cursor vertically.
-<!-- ##### FUNCTION gtk_model_simple_new ##### -->
+<!-- ##### SIGNAL GtkEditable::move-to-column ##### -->
<para>
-
+An action signal. Move the cursor to the given column.
</para>
-@Returns:
+@editable: the object which received the signal.
+@column: the column to move to. (A negative value indicates
+ the last column)
-<!-- ##### FUNCTION gtk_marshal_BOOL__NONE ##### -->
+<!-- ##### SIGNAL GtkEditable::move-to-row ##### -->
<para>
-
+An action signal. Move the cursor to the given row.
</para>
-@object:
-@func:
-@func_data:
-@args:
+@editable: the object which received the signal.
+@row: the row to move to. (A negative value indicates
+ the last row)
-<!-- ##### FUNCTION gtk_type_free ##### -->
+<!-- ##### SIGNAL GtkEditable::move-word ##### -->
<para>
-Given the type of an object and a pointer to it, the object is freed.
+An action signal. Move the cursor by words.
</para>
-@type: GtkType
-@mem: gpointer to the object
-
-<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:Short_Description ##### -->
-
-
+@editable: the object which received the signal.
+@num_words: The number of words to move the
+cursor. (Can be negative).
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_POINTER ##### -->
+<!-- ##### SIGNAL GtkEditable::paste-clipboard ##### -->
<para>
-
+An action signal. Causes the contents of the clipboard to
+be pasted into the editable widget at the current cursor
+position.
</para>
-@object:
-@func:
-@func_data:
-@args:
+@editable: the object which received the signal.
-<!-- ##### STRUCT GtkMenuPath ##### -->
+<!-- ##### SIGNAL GtkEditable::set-editable ##### -->
<para>
-
+Determines if the user can edit the text in the editable
+widget or not. This is meant to be overriden by
+child classes and should not generally useful to
+applications.
</para>
-@path:
-@widget:
+@editable: the object which received the signal.
+@is_editable: %TRUE if the user is allowed to edit the text
+ in the widget.
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT ##### -->
+<!-- ##### ARG GtkEditable:editable ##### -->
<para>
-
+A boolean indicating whether the widget is editable by
+the user.
</para>
-<!-- ##### STRUCT GtkStatusbarMsg ##### -->
+<!-- ##### ARG GtkEditable:text-position ##### -->
<para>
-Holds the data for a statusbar message. <structfield>text</structfield> holds the actual text string. <structfield>context_id</structfield> is the context that this message is associated with, and <structfield>message_id</structfield> is this particular message's identifier. However, these fields should not be modified directly.
+The position of the cursor.
</para>
-@text:
-@context_id:
-@message_id:
-<!-- ##### FUNCTION gtk_widget_render_stock_icon ##### -->
+<!-- ##### ENUM GtkFontFilterType ##### -->
<para>
-
+A set of bit flags used to specify the filter being set
+when calling gtk_font_selection_dialog_set_filter() or
+gtk_font_selection_set_filter().
</para>
-@widget:
-@stock_id:
-@size:
-@detail:
-@Returns:
-
-<!-- ##### SECTION ./tmpl/gtkprivate.sgml:Title ##### -->
-Private Information
-
+@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
+@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the
+'Filter' page of the #GtkFontSelection widget.
-<!-- ##### ARG GtkEditable:text-position ##### -->
+<!-- ##### ENUM GtkFontType ##### -->
<para>
-The position of the cursor.
+A set of bit flags used to specify the type of fonts shown
+when calling gtk_font_selection_dialog_set_filter() or
+gtk_font_selection_set_filter().
</para>
+@GTK_FONT_BITMAP: bitmap fonts.
+@GTK_FONT_SCALABLE: scalable fonts.
+@GTK_FONT_SCALABLE_BITMAP: scaled bitmap fonts.
+@GTK_FONT_ALL: a bitwise combination of all of the above.
-<!-- ##### FUNCTION gtk_theme_engine_register_type ##### -->
+<!-- ##### STRUCT GtkIMContextSimple ##### -->
<para>
</para>
-@engine:
-@parent_type:
-@type_name:
-@type_info:
-@Returns:
+@object:
+@tables:
+@compose_buffer:
+@tentative_match:
+@tentative_match_len:
-<!-- ##### FUNCTION gtk_menu_factory_find ##### -->
+<!-- ##### STRUCT GtkLabelWord ##### -->
+<para>\r
+Internal to #GtkLabel.\r
+</para>
+
+
+<!-- ##### USER_FUNCTION GtkMenuCallback ##### -->
<para>
</para>
-@factory:
-@path:
-@Returns:
+@widget:
+@user_data:
<!-- ##### STRUCT GtkMenuEntry ##### -->
<para>
@callback_data:
@widget:
-<!-- ##### SIGNAL GtkEditable::paste-clipboard ##### -->
+<!-- ##### STRUCT GtkMenuFactory ##### -->
<para>
-An action signal. Causes the contents of the clipboard to
-be pasted into the editable widget at the current cursor
-position.
+
</para>
-@editable: the object which received the signal.
+@path:
+@type:
+@accel_group:
+@widget:
+@subfactories:
-<!-- ##### FUNCTION gtk_window_add_embedded_xid ##### -->
+<!-- ##### ENUM GtkMenuFactoryType ##### -->
<para>
</para>
-@window:
-@xid:
+@GTK_MENU_FACTORY_MENU:
+@GTK_MENU_FACTORY_MENU_BAR:
+@GTK_MENU_FACTORY_OPTION_MENU:
-<!-- ##### FUNCTION gtk_tree_view_column_set_header_active ##### -->
+<!-- ##### STRUCT GtkMenuPath ##### -->
<para>
</para>
-@tree_column:
-@active:
+@path:
+@widget:
-<!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->
+<!-- ##### STRUCT GtkModelSimple ##### -->
<para>
-Define a signal-handler for a new signal on an already defined
-object.
-</para>
-@klass: the object class to define the signal for.
-@name: the name of the signal.
-@signal_flags: the default emission behavior for the signal.
-See gtk_signal_new().
-@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array
-of arguments, and invokes the function using the appropriate
-calling conventions. Usually just select a function
-out of gtkmarshal.h.
-@return_val: specify the return-value type for the signal (possibly
-#GTK_TYPE_NONE).
-@nparams: specify the number of parameters the signal
-receives from the caller of gtk_signal_emit().
-@params: array of #GtkTypes the signal handlers for this signal
-should have in their prototype (of length nparams).
-@Returns: the signal id. (See #GtkSignals)
+</para>
-<!-- ##### FUNCTION gtk_marshal_NONE__BOOL ##### -->
-<para>
+@parent:
+@stamp:
+<!-- ##### ARG GtkObject:object-signal ##### -->
+<para>
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object, so that the user data and objects
+and swapped when the signal handler is invoked.
</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-<!-- ##### FUNCTION gtk_tree_view_column_set_header_clickable ##### -->
<para>
-
+This is useful for handlers that are primarily notifying
+other objects and could just invoke an already existing function
+if the parameters were swapped.
+See gtk_signal_connect_object() for more details.
</para>
-@tree_column:
-@active:
-<!-- ##### FUNCTION gtk_color_selection_set_opacity ##### -->
+<!-- ##### ARG GtkObject:object-signal-after ##### -->
<para>
-Controls whether opacity can be set with the #GtkColorSelection.
-If this functionality is enabled, the necessary additional widgets
-are added to the #GtkColorSelection and the opacity value can be
-retrieved via the fourth value in the color array returned by
-the gtk_color_selection_get_color() function.
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object, so that the user data and objects
+and swapped when the signal handler is invoked,
+and so that the handler is invoked after all others.
</para>
-
-@colorsel: a #GtkColorSelection.
-@use_opacity: a boolean indicating whether the opacity selection
-is enabled.
-
-<!-- ##### FUNCTION gtk_marshal_INT__POINTER ##### -->
<para>
-
+See gtk_signal_connect_object_after() for more details.
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### SECTION ./tmpl/gtkmarshal.sgml:See_Also ##### -->
+<!-- ##### ARG GtkObject:signal ##### -->
<para>
-<variablelist>
-
-<varlistentry>
-<term>#GtkSignal</term>
-<listitem><para>The signal handling functions (of which marshallers are
-really an implementation detail).</para></listitem>
-</varlistentry>
-
-</variablelist>
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object.
</para>
-<!-- ##### SIGNAL GtkEditable::move-word ##### -->
+<!-- ##### ARG GtkObject:signal-after ##### -->
<para>
-An action signal. Move the cursor by words.
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object, so that the signal is always run
+after other user handlers and the default handler.
</para>
-@editable: the object which received the signal.
-@num_words: The number of words to move the
-cursor. (Can be negative).
-<!-- ##### STRUCT GtkTreeViewPrivate ##### -->
+<!-- ##### ENUM GtkPrivateFlags ##### -->
<para>
</para>
-@model:
-@flags:
-@tree:
-@tab_offset:
-@button_pressed_node:
-@button_pressed_tree:
-@children:
-@width:
-@height:
-@hadjustment:
-@vadjustment:
-@bin_window:
-@header_window:
-@anchor:
-@cursor:
-@cursor_drag:
-@xor_gc:
-@drag_pos:
-@x_drag:
-@prelight_node:
-@prelight_tree:
-@prelight_offset:
-@selection:
-@columns:
-@column:
-@header_height:
+@PRIVATE_GTK_USER_STYLE:
+@PRIVATE_GTK_RESIZE_PENDING:
+@PRIVATE_GTK_RESIZE_NEEDED:
+@PRIVATE_GTK_LEAVE_PENDING:
+@PRIVATE_GTK_HAS_SHAPE_MASK:
+@PRIVATE_GTK_IN_REPARENT:
+@PRIVATE_GTK_DIRECTION_SET:
+@PRIVATE_GTK_DIRECTION_LTR:
-<!-- ##### MACRO GTK_WIDGET_RESIZE_NEEDED ##### -->
+<!-- ##### USER_FUNCTION GtkSignalDestroy ##### -->
<para>
-
+A function which you can use to clean up when the
+signal handler is destroyed.
</para>
-
-@obj:
-
-<!-- ##### MACRO GTK_NOTE ##### -->
<para>
-
+For example, if your handler requires a few variables
+that you made into a struct and allocated (using g_new()
+or something), then you will probably want to free
+it as soon as the hook is destroyed. This will
+allow you to do that. (For this in particular
+it is convenient to pass g_free() as a #GtkSignalDestroy
+function).
</para>
-@type:
-@action:
+@data: The user data associated with the hook that is being
+destroyed.
-<!-- ##### FUNCTION gtk_object_arg_set ##### -->
+<!-- ##### USER_FUNCTION GtkSignalMarshal ##### -->
<para>
-Private function to set an argument and argument info to an object.
+This is currently a hack left in for a scheme wrapper library.
+It may be removed.
</para>
-
-@object: the object whose argument should be set.
-@arg: the argument.
-@info: infomation about this type of argument in general.
-
-<!-- ##### ENUM GtkTextViewDeleteType ##### -->
<para>
-
+Don't use it.
</para>
-@GTK_TEXT_DELETE_CHAR:
-@GTK_TEXT_DELETE_HALF_WORD:
-@GTK_TEXT_DELETE_WHOLE_WORD:
-@GTK_TEXT_DELETE_HALF_WRAPPED_LINE:
-@GTK_TEXT_DELETE_WHOLE_WRAPPED_LINE:
-@GTK_TEXT_DELETE_HALF_LINE:
-@GTK_TEXT_DELETE_WHOLE_LINE:
-@GTK_TEXT_DELETE_WHITESPACE:
-@GTK_TEXT_DELETE_WHITESPACE_LEAVE_ONE:
+@object: The object which emits the signal.
+@data: The user data associated with the hook.
+@nparams: The number of parameters to the function.
+@args: The actual values of the arguments.
+@arg_types: The types of the arguments.
+@return_type: The type of the return value from the function
+or #GTK_TYPE_NONE for no return value.
-<!-- ##### STRUCT GtkIMContextSimple ##### -->
+<!-- ##### STRUCT GtkSignalQuery ##### -->
<para>
-
+This structure contains all the information about a particular
+signal: its name, the type it affects, the signature of the handlers,
+and its unique identifying integer.
</para>
-@object:
-@tables:
-@compose_buffer:
-@tentative_match:
-@tentative_match_len:
+@object_type:
+@signal_id:
+@signal_name:
+@is_user_signal:
+@signal_flags:
+@return_val:
+@nparams:
+@params:
-<!-- ##### MACRO GTK_TYPE_FLAT_FIRST ##### -->
+<!-- ##### STRUCT GtkStatusbarMsg ##### -->
<para>
-The first "flat" (no struct) enumerated type value.
+Holds the data for a statusbar message. <structfield>text</structfield> holds the actual text string. <structfield>context_id</structfield> is the context that this message is associated with, and <structfield>message_id</structfield> is this particular message's identifier. However, these fields should not be modified directly.
</para>
+@text:
+@context_id:
+@message_id:
-<!-- ##### FUNCTION gtk_widget_getv ##### -->
+<!-- ##### STRUCT GtkTextBTree ##### -->
<para>
</para>
-@widget:
-@nargs:
-@args:
-<!-- ##### FUNCTION gtk_tree_model_sort_resort ##### -->
+<!-- ##### SIGNAL GtkTextBuffer::delete-text ##### -->
<para>
</para>
-@tree_model_sort:
+@textbuffer: the object which received the signal.
+@arg1:
+@arg2:
+@arg3:
-<!-- ##### FUNCTION gtk_tree_view_column_get_col_type ##### -->
+<!-- ##### STRUCT GtkTextTabArray ##### -->
<para>
</para>
-@tree_column:
-@Returns:
-<!-- ##### FUNCTION gtk_menu_factory_new ##### -->
+<!-- ##### ARG GtkTextTag:font-set ##### -->
<para>
</para>
-@type:
-@Returns:
-<!-- ##### FUNCTION gtk_object_constructed ##### -->
-<para>
-Mark an allocated object as constructed.
-This is used for situations
-that require precise control of the construction process.
-</para>
-<para>
-This is done when gtk_object_default_construct() is inadequate.
-In #GtkCList the need arises because #GtkCList does construction work that
-must happen <emphasis>after</emphasis> its derivers. This work
-cannot be done in an initializer function, so an alternate
-constructor is mandatory. It calls gtk_object_constructed() to
-indicate it has done its job, so that no other constructor will
-be invoked.
-</para>
+<!-- ##### ARG GtkTextTag:justify ##### -->
<para>
-Normally this function is just automatically run from
-gtk_object_default_construct().
+A #GtkJustification for the text. This is only used when the tag is
+applied to the first character in a paragraph.
</para>
-@object: object which has been constructed. This is usually
-done automatically by gtk_object_new() and gtk_object_newv().
-<!-- ##### FUNCTION gtk_object_default_construct ##### -->
-<para>
-This function is called to construct arguments that haven't been initialized
-but have the #GTK_ARG_CONSTRUCT flag set.
-</para>
+<!-- ##### ARG GtkTextTag:justify-set ##### -->
<para>
-All number arguments are set to 0. All pointers and strings
-are set to NULL.
+
</para>
+
+
+<!-- ##### ARG GtkTextTag:left-wrapped-line-margin ##### -->
<para>
-Normally invoked by gtk_object_new() automatically; gtk_type_new() can
-be used to bypass it.
+Pixel width of the left margin of the text for lines after the first
+line in a wrapped paragraph.
</para>
-@object: the object to initialize.
-<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_UINT_ENUM ##### -->
+<!-- ##### ARG GtkTextTag:left-wrapped-line-margin-set ##### -->
<para>
</para>
-<!-- ##### STRUCT GtkLabelWord ##### -->
-<para>\r
-Internal to #GtkLabel.\r
+<!-- ##### ARG GtkTextTag:offset ##### -->
+<para>
+Pixels to offset the text horizontally or vertically, useful to
+produce superscript and subscript.
</para>
-<!-- ##### FUNCTION gtk_text_buffer_spew ##### -->
+<!-- ##### ARG GtkTextTag:offset-set ##### -->
<para>
</para>
-@buffer:
-<!-- ##### ARG GtkTextTag:font-set ##### -->
+<!-- ##### ARG GtkTextTag:overstrike ##### -->
<para>
</para>
-<!-- ##### FUNCTION gtk_object_arg_get_info ##### -->
+<!-- ##### ARG GtkTextTag:overstrike-set ##### -->
<para>
-Query information about an argument type.
+
</para>
-@object_type: type of object to query about.
-@arg_name: name of the argument.
-@info_p: pointer to be filled in with a pointer to the GtkArgInfo.
-@Returns: an error message, or NULL on success.
-It is the caller's responsibility to call g_free() in the event of error.
-<!-- ##### ENUM GtkTreeSelectionType ##### -->
+<!-- ##### SIGNAL GtkTextView::copy-text ##### -->
<para>
</para>
-@GTK_TREE_SELECTION_SINGLE:
-@GTK_TREE_SELECTION_MULTI:
+@textview: the object which received the signal.
-<!-- ##### ARG GtkObject:signal-after ##### -->
+<!-- ##### SIGNAL GtkTextView::cut-text ##### -->
<para>
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects
-the signal to the object, so that the signal is always run
-after other user handlers and the default handler.
+
</para>
+@textview: the object which received the signal.
-<!-- ##### STRUCT GtkTextTabArray ##### -->
+<!-- ##### SIGNAL GtkTextView::delete ##### -->
<para>
</para>
+@textview: the object which received the signal.
+@arg1:
+@arg2:
-<!-- ##### ARG GtkTextTag:overstrike ##### -->
+<!-- ##### SIGNAL GtkTextView::delete-at-cursor ##### -->
<para>
</para>
+@textview: the object which received the signal.
+@arg1:
+@arg2:
-<!-- ##### MACRO GTK_TREE_SELECTION ##### -->
+<!-- ##### SIGNAL GtkTextView::delete-text ##### -->
<para>
-A macro that returns a GList that contains the selection of the root tree of @obj.
-</para>
-@obj: A pointer to the #GtkTree. @obj will accept any pointer, but it the pointer does not point to a #GtkTree, the results are undefined.
-
-<!-- ##### FUNCTION gtk_editable_changed ##### -->
-<para>
-Causes the "changed" signal to be emitted.
</para>
-@editable: a #GtkEditable widget.
+@textview: the object which received the signal.
+@arg1:
+@arg2:
-<!-- ##### FUNCTION gtk_object_setv ##### -->
+<!-- ##### SIGNAL GtkTextView::insert ##### -->
<para>
-Set an array of arguments.
+
</para>
-@object: the object whose arguments should be set.
-@n_args: the number of arguments to set.
-@args: the desired values, as an array of #GtkArgs (which contain
-the names, types, and values of the arguments).
+@textview: the object which received the signal.
+@arg1:
<!-- ##### SIGNAL GtkTextView::move ##### -->
<para>
@arg2:
@arg3:
-<!-- ##### MACRO GTK_WIDGET_HAS_SHAPE_MASK ##### -->
+<!-- ##### SIGNAL GtkTextView::move-insert ##### -->
<para>
</para>
-@obj:
+@textview: the object which received the signal.
+@arg1:
+@arg2:
+@arg3:
-<!-- ##### FUNCTION gtk_text_buffer_copy ##### -->
+<!-- ##### SIGNAL GtkTextView::paste-text ##### -->
<para>
</para>
-@buffer:
-@time:
+@textview: the object which received the signal.
-<!-- ##### FUNCTION gtk_text_mark_ref ##### -->
+<!-- ##### SIGNAL GtkTextView::scroll-text ##### -->
<para>
</para>
-@mark:
-@Returns:
+@textview: the object which received the signal.
+@arg1:
-<!-- ##### ARG GtkTextTag:offset ##### -->
+<!-- ##### ENUM GtkTextViewDeleteType ##### -->
<para>
-Pixels to offset the text horizontally or vertically, useful to
-produce superscript and subscript.
+
</para>
+@GTK_TEXT_DELETE_CHAR:
+@GTK_TEXT_DELETE_HALF_WORD:
+@GTK_TEXT_DELETE_WHOLE_WORD:
+@GTK_TEXT_DELETE_HALF_WRAPPED_LINE:
+@GTK_TEXT_DELETE_WHOLE_WRAPPED_LINE:
+@GTK_TEXT_DELETE_HALF_LINE:
+@GTK_TEXT_DELETE_WHOLE_LINE:
+@GTK_TEXT_DELETE_WHITESPACE:
+@GTK_TEXT_DELETE_WHITESPACE_LEAVE_ONE:
-<!-- ##### SIGNAL GtkEditable::insert-text ##### -->
+<!-- ##### ENUM GtkTextViewMovementStep ##### -->
<para>
-This signal is emitted when text is inserted into
-the widget by the user. The default handler for
-this signal will normally be responsible for inserting
-the text, so by connecting to this signal and then
-stopping the signal with gtk_signal_emit_stop(), it
-is possible to modify the inserted text, or prevent
-it from being inserted entirely.
+
</para>
-@editable: the object which received the signal.
-@new_text: the new text to insert.
-@new_text_length: the length of the new text.
-@position: the position at which to insert the new text.
- this is an in-out paramter. After the signal
- emission is finished, it should point after
- the newly inserted text.
+@GTK_TEXT_MOVEMENT_CHAR:
+@GTK_TEXT_MOVEMENT_POSITIONS:
+@GTK_TEXT_MOVEMENT_WORD:
+@GTK_TEXT_MOVEMENT_WRAPPED_LINE:
+@GTK_TEXT_MOVEMENT_LINE:
+@GTK_TEXT_MOVEMENT_LINE_ENDS:
+@GTK_TEXT_MOVEMENT_BUFFER_ENDS:
-<!-- ##### FUNCTION gtk_editable_claim_selection ##### -->
+<!-- ##### ENUM GtkTextViewScrollType ##### -->
<para>
-Claim or disclaim ownership of the PRIMARY X selection.
+
</para>
-@editable: a #GtkEditable widget.
-@claim: if %TRUE, claim the selection, otherwise, disclaim it.
-@time: the timestamp for claiming the selection.
+@GTK_TEXT_SCROLL_TO_TOP:
+@GTK_TEXT_SCROLL_TO_BOTTOM:
+@GTK_TEXT_SCROLL_PAGE_DOWN:
+@GTK_TEXT_SCROLL_PAGE_UP:
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT ##### -->
+<!-- ##### STRUCT GtkThemeEngine ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->
+<!-- ##### ENUM GtkTreeSelectionType ##### -->
<para>
-Get the array of signals defined for this object.
+
</para>
-@obj: the object to fetch the signals from.
+@GTK_TREE_SELECTION_SINGLE:
+@GTK_TREE_SELECTION_MULTI:
-<!-- ##### FUNCTION gtk_object_query_args ##### -->
+<!-- ##### ENUM GtkTreeViewColumnType ##### -->
<para>
-Get all the arguments that may be used for a given type.
+
</para>
+
+@GTK_TREE_VIEW_COLUMN_RESIZEABLE:
+@GTK_TREE_VIEW_COLUMN_AUTOSIZE:
+@GTK_TREE_VIEW_COLUMN_FIXED:
+
+<!-- ##### STRUCT GtkTreeViewPrivate ##### -->
<para>
-In Java, this type of mechanism is called
-<wordasword>introspection</wordasword>. It is used by applications
-like Glade, that have to determine what can be done to an object
-at run-time.
+
</para>
-@class_type: the GtkType of the ObjectClass
-(returned from GTK_OBJECT_CLASS(class)->type for example).
-@arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to
-each argument. You must g_free() this if you request it.
-@n_args: the number of arguments is returned in this field.
-@Returns: an array of arguments, that you must deallocate with g_free().
+@model:
+@flags:
+@tree:
+@tab_offset:
+@button_pressed_node:
+@button_pressed_tree:
+@children:
+@width:
+@height:
+@hadjustment:
+@vadjustment:
+@bin_window:
+@header_window:
+@anchor:
+@cursor:
+@cursor_drag:
+@xor_gc:
+@drag_pos:
+@x_drag:
+@prelight_node:
+@prelight_tree:
+@prelight_offset:
+@selection:
+@columns:
+@column:
+@header_height:
-<!-- ##### SIGNAL GtkEditable::move-to-column ##### -->
+<!-- ##### STRUCT GtkTypeQuery ##### -->
<para>
-An action signal. Move the cursor to the given column.
+A structure used to return values from @gtk_type_query.
</para>
-@editable: the object which received the signal.
-@column: the column to move to. (A negative value indicates
- the last column)
+@type:
+@type_name:
+@object_size:
+@class_size:
-<!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:Title ##### -->
-gtkenums.sgml
+<!-- ##### ARG GtkVScale:adjustment ##### -->
+<para>
+the #GtkAdjustment which sets the range of the scale.
+</para>
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT_POINTER ##### -->
+<!-- ##### ARG GtkVScrollbar:adjustment ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
-<!-- ##### USER_FUNCTION GtkMenuCallback ##### -->
+<!-- ##### SIGNAL GtkViewport::set-scroll-adjustments ##### -->
<para>
</para>
-@widget:
-@user_data:
+@viewport: the object which received the signal.
+@arg1:
+@arg2:
-<!-- ##### FUNCTION gtk_type_check_object_cast ##### -->
+<!-- ##### ARG GtkViewport:hadjustment ##### -->
<para>
-Given a pointer to a GtkTypeObject @type_object, and a GtkType @cast_type,
-make sure that it's okay to cast @type_object into a @cast_type.
+
</para>
-@type_object: GtkTypeObject*
-@cast_type: GtkType
-@Returns: the same GtkTypeObject* as @type_object
-<!-- ##### FUNCTION gtk_tree_model_sort_set_sort_col ##### -->
+<!-- ##### ARG GtkViewport:shadow-type ##### -->
<para>
</para>
-@tree_model_sort:
-@sort_col:
-<!-- ##### FUNCTION gtk_themes_exit ##### -->
+<!-- ##### ARG GtkViewport:vadjustment ##### -->
<para>
</para>
-@error_code:
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_POINTER_POINTER ##### -->
+<!-- ##### SIGNAL GtkWidget::add-accelerator ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@widget: the object which received the signal.
+@accel_signal_id:
+@accel_group:
+@accel_key:
+@accel_mods:
+@accel_flags:
-<!-- ##### MACRO gtk_marshal_NONE__OBJECT ##### -->
+<!-- ##### SIGNAL GtkWidget::button-press-event ##### -->
<para>
</para>
+@widget: the object which received the signal.
+@event:
+@Returns:
-<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Long_Description ##### -->
+<!-- ##### SIGNAL GtkWidget::button-release-event ##### -->
<para>
</para>
+@widget: the object which received the signal.
+@event:
+@Returns:
-<!-- ##### FUNCTION gtk_type_set_varargs_type ##### -->
+<!-- ##### SIGNAL GtkWidget::client-event ##### -->
<para>
-Set the varargs type for a fundamental type @foreign_type.
+
</para>
-@foreign_type: Must be a GtkType with a sequence number of zero. Must not be a
-fundamental type.
-@varargs_type: Must be a GtkType which is either structured or flag, or NONE.
+@widget: the object which received the signal.
+@event:
+@Returns:
-<!-- ##### FUNCTION gtk_type_check_class_cast ##### -->
+<!-- ##### SIGNAL GtkWidget::configure-event ##### -->
<para>
-Given a GtkTypeClass pointer @klass, and a GtkType @cast_type, make
-sure that it's okay to cast something of that @klass into a @cast_type.
+
</para>
-@klass: GtkTypeClass*
-@cast_type: GtkType
-@Returns: Always return @klass.
+@widget: the object which received the signal.
+@event:
+@Returns:
-<!-- ##### ARG GtkObject:object-signal-after ##### -->
-<para>
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects
-the signal to the object, so that the user data and objects
-and swapped when the signal handler is invoked,
-and so that the handler is invoked after all others.
-</para>
+<!-- ##### SIGNAL GtkWidget::debug-msg ##### -->
<para>
-See gtk_signal_connect_object_after() for more details.
+
</para>
+@widget: the object which received the signal.
+@message:
-<!-- ##### FUNCTION gtk_menu_factory_destroy ##### -->
+<!-- ##### SIGNAL GtkWidget::delete-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::destroy-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::direction-changed ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@arg1:
+
+<!-- ##### SIGNAL GtkWidget::drag-begin ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+
+<!-- ##### SIGNAL GtkWidget::drag-data-delete ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+
+<!-- ##### SIGNAL GtkWidget::drag-data-get ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+@data:
+@info:
+@time:
+
+<!-- ##### SIGNAL GtkWidget::drag-data-received ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+@x:
+@y:
+@data:
+@info:
+@time:
+
+<!-- ##### SIGNAL GtkWidget::drag-drop ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+@x:
+@y:
+@time:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::drag-end ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+
+<!-- ##### SIGNAL GtkWidget::drag-leave ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+@time:
+
+<!-- ##### SIGNAL GtkWidget::drag-motion ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@drag_context:
+@x:
+@y:
+@time:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::draw ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@area:
+
+<!-- ##### SIGNAL GtkWidget::draw-default ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::draw-focus ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::enter-notify-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::expose-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::focus-in-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::focus-out-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::grab-focus ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::hide ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::key-press-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::key-release-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::leave-notify-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::map ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::map-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::motion-notify-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::no-expose-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::parent-set ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@old_parent:
+
+<!-- ##### SIGNAL GtkWidget::property-notify-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::proximity-in-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::proximity-out-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::realize ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::remove-accelerator ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@accel_group:
+@accel_key:
+@accel_mods:
+
+<!-- ##### SIGNAL GtkWidget::scroll-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::selection-clear-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::selection-get ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@data:
+@info:
+@time:
+
+<!-- ##### SIGNAL GtkWidget::selection-notify-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::selection-received ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@data:
+@time:
+
+<!-- ##### SIGNAL GtkWidget::selection-request-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::show ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::size-allocate ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@allocation:
+
+<!-- ##### SIGNAL GtkWidget::size-request ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@requisition:
+
+<!-- ##### SIGNAL GtkWidget::state-changed ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@state:
+
+<!-- ##### SIGNAL GtkWidget::style-set ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@previous_style:
+
+<!-- ##### SIGNAL GtkWidget::unmap ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::unmap-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWidget::unrealize ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+
+<!-- ##### SIGNAL GtkWidget::visibility-notify-event ##### -->
+<para>
+
+</para>
+
+@widget: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### ARG GtkWidget:app-paintable ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:can-default ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:can-focus ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:composite-child ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:events ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:extension-events ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:has-default ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:has-focus ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:height ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:name ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:parent ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:receives-default ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:sensitive ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:style ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:visible ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:width ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:x ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWidget:y ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SIGNAL GtkWindow::frame-event ##### -->
+<para>
+
+</para>
+
+@window: the object which received the signal.
+@event:
+@Returns:
+
+<!-- ##### SIGNAL GtkWindow::set-focus ##### -->
+<para>
+
+</para>
+
+@window: the object which received the signal.
+@widget:
+
+<!-- ##### ARG GtkWindow:allow-grow ##### -->
+<para>
+If the window can be resized to a larger size by the user.
+</para>
+
+
+<!-- ##### ARG GtkWindow:allow-shrink ##### -->
+<para>
+If the window can be resized to a smaller size by the user.
+</para>
+
+
+<!-- ##### ARG GtkWindow:auto-shrink ##### -->
+<para>
+If the window shrinks automatically when widgets within it shrink.
+</para>
+
+
+<!-- ##### ARG GtkWindow:default-height ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWindow:default-width ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWindow:destroy-with-parent ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG GtkWindow:modal ##### -->
+<para>
+If the window is modal, i.e. it grabs all GTK+ events.
+</para>
+
+
+<!-- ##### ARG GtkWindow:title ##### -->
+<para>
+The title of the window.
+</para>
+
+
+<!-- ##### ARG GtkWindow:type ##### -->
+<para>
+The type of the window.
+</para>
+
+
+<!-- ##### ARG GtkWindow:window-position ##### -->
+<para>
+The position of the window.
+</para>
+
+
+<!-- ##### FUNCTION gtk_accel_group_marshal_add ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_accel_group_marshal_remove ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_clist_construct ##### -->
+<para>
+Initializes a previously allocated #GtkCList widget for use. This should not
+normally be used to create a #GtkCList widget. Use gtk_clist_new() instead.
+</para>
+
+@clist: A pointer to an uninitialized #GtkCList widget.
+@columns: The number of columns the #GtkCList should have.
+@titles: An array of strings that should be used as the titles i
+of the columns. There should be enough strings in the array for
+the number of columns specified.
+
+<!-- ##### FUNCTION gtk_color_selection_set_opacity ##### -->
+<para>
+Controls whether opacity can be set with the #GtkColorSelection.
+If this functionality is enabled, the necessary additional widgets
+are added to the #GtkColorSelection and the opacity value can be
+retrieved via the fourth value in the color array returned by
+the gtk_color_selection_get_color() function.
+</para>
+
+@colorsel: a #GtkColorSelection.
+@use_opacity: a boolean indicating whether the opacity selection
+is enabled.
+
+<!-- ##### FUNCTION gtk_container_get_toplevels ##### -->
+<para>
+
+</para>
+
+@Returns:
+
+<!-- ##### FUNCTION gtk_container_register_toplevel ##### -->
+<para>
+
+</para>
+
+@container:
+
+<!-- ##### FUNCTION gtk_container_unregister_toplevel ##### -->
+<para>
+
+</para>
+
+@container:
+
+<!-- ##### FUNCTION gtk_ctree_construct ##### -->
+<para>
+This function is not usually used by users.
+</para>
+
+@ctree:
+@columns:
+@tree_column:
+@titles:
+
+<!-- ##### VARIABLE gtk_debug_flags ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_draw_cross ##### -->
+<para>
+
+</para>
+
+@style:
+@window:
+@state_type:
+@shadow_type:
+@x:
+@y:
+@width:
+@height:
+
+<!-- ##### FUNCTION gtk_draw_oval ##### -->
+<para>
+
+</para>
+
+@style:
+@window:
+@state_type:
+@shadow_type:
+@x:
+@y:
+@width:
+@height:
+
+<!-- ##### FUNCTION gtk_draw_ramp ##### -->
+<para>
+
+</para>
+
+@style:
+@window:
+@state_type:
+@shadow_type:
+@arrow_type:
+@x:
+@y:
+@width:
+@height:
+
+<!-- ##### FUNCTION gtk_editable_changed ##### -->
+<para>
+Causes the "changed" signal to be emitted.
+</para>
+
+@editable: a #GtkEditable widget.
+
+<!-- ##### FUNCTION gtk_editable_claim_selection ##### -->
+<para>
+Claim or disclaim ownership of the PRIMARY X selection.
+</para>
+
+@editable: a #GtkEditable widget.
+@claim: if %TRUE, claim the selection, otherwise, disclaim it.
+@time: the timestamp for claiming the selection.
+
+<!-- ##### FUNCTION gtk_font_selection_dialog_set_filter ##### -->
+<para>
+Sets one of the two font filters, to limit the fonts shown.
+</para>
+
+@fsd: a #GtkFontSelectionDialog.
+@filter_type: which of the two font filters to set, either
+#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter
+can be changed by the user, but the base filter is permanent.
+@font_type: the types of font to be shown. This is a bitwise combination of
+#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP,
+or #GTK_FONT_ALL to show all three font types.
+@foundries: a NULL-terminated array of strings containing foundry names which
+will be shown, or NULL to show all foundries.
+@weights: a NULL-terminated array of strings containing weight names which
+will be shown, or NULL to show all weights.
+@slants: a NULL-terminated array of strings containing slant names which
+will be shown, or NULL to show all slants.
+@setwidths: a NULL-terminated array of strings containing setwidth names which
+will be shown, or NULL to show all setwidths.
+@spacings: a NULL-terminated array of strings containing spacings which
+will be shown, or NULL to show all spacings.
+@charsets: a NULL-terminated array of strings containing charset names which
+will be shown, or NULL to show all charsets.
+
+<!-- ##### FUNCTION gtk_font_selection_set_filter ##### -->
+<para>
+Sets one of the two font filters, to limit the fonts shown.
+</para>
+
+@fontsel: a #GtkFontSelection.
+@filter_type: which of the two font filters to set, either
+#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter
+can be changed by the user, but the base filter is permanent.
+@font_type: the types of font to be shown. This is a bitwise combination of
+#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP,
+or #GTK_FONT_ALL to show all three font types.
+@foundries: a NULL-terminated array of strings containing foundry names which
+will be shown, or NULL to show all foundries.
+@weights: a NULL-terminated array of strings containing weight names which
+will be shown, or NULL to show all weights.
+@slants: a NULL-terminated array of strings containing slant names which
+will be shown, or NULL to show all slants.
+@setwidths: a NULL-terminated array of strings containing setwidth names which
+will be shown, or NULL to show all setwidths.
+@spacings: a NULL-terminated array of strings containing spacings which
+will be shown, or NULL to show all spacings.
+@charsets: a NULL-terminated array of strings containing charset names which
+will be shown, or NULL to show all charsets.
+
+<!-- ##### FUNCTION gtk_icon_factory_get_type ##### -->
+<para>
+
+</para>
+
+@Returns:
+
+<!-- ##### FUNCTION gtk_identifier_get_type ##### -->
+<para>
+Get the type of GtkIdentifier.
+</para>
+
+@Returns: GtkType -- the enumerated type of something.
+
+<!-- ##### FUNCTION gtk_im_context_simple_add_table ##### -->
+<para>
+
+</para>
+
+@context_simple:
+@data:
+@max_seq_len:
+@n_seqs:
+
+<!-- ##### FUNCTION gtk_im_context_simple_new ##### -->
+<para>
+
+</para>
+
+@Returns:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__NONE ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_BOOL__POINTER_INT_INT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_ENUM__ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_INT__INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_INT__POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_INT__POINTER_CHAR_CHAR ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__BOOL ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__BOXED ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK_C_CALLBACK ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT_BOOL ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT_BOOL ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__NONE ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__OBJECT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_INT_INT_POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_STRING_STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__STRING_INT_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_ENUM_ENUM_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_UINT_ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_menu_factory_add_entries ##### -->
+<para>
+
+</para>
+
+@factory:
+@entries:
+@nentries:
+
+<!-- ##### FUNCTION gtk_menu_factory_add_subfactory ##### -->
+<para>
+
+</para>
+
+@factory:
+@subfactory:
+@path:
+
+<!-- ##### FUNCTION gtk_menu_factory_destroy ##### -->
+<para>
+
+</para>
+
+@factory:
+
+<!-- ##### FUNCTION gtk_menu_factory_find ##### -->
+<para>
+
+</para>
+
+@factory:
+@path:
+@Returns:
+
+<!-- ##### FUNCTION gtk_menu_factory_new ##### -->
+<para>
+
+</para>
+
+@type:
+@Returns:
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_entries ##### -->
+<para>
+
+</para>
+
+@factory:
+@entries:
+@nentries:
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_paths ##### -->
+<para>
+
+</para>
+
+@factory:
+@paths:
+@npaths:
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_subfactory ##### -->
<para>
</para>
@factory:
+@subfactory:
+@path:
+
+<!-- ##### FUNCTION gtk_model_simple_new ##### -->
+<para>
+
+</para>
+
+@Returns:
+
+<!-- ##### FUNCTION gtk_model_simple_node_changed ##### -->
+<para>
+
+</para>
+
+@simple:
+@path:
+@iter:
+
+<!-- ##### FUNCTION gtk_model_simple_node_child_toggled ##### -->
+<para>
+
+</para>
+
+@simple:
+@path:
+@iter:
+
+<!-- ##### FUNCTION gtk_model_simple_node_deleted ##### -->
+<para>
+
+</para>
+
+@simple:
+@path:
+@iter:
+
+<!-- ##### FUNCTION gtk_model_simple_node_inserted ##### -->
+<para>
+
+</para>
+
+@simple:
+@path:
+@iter:
+
+<!-- ##### FUNCTION gtk_object_arg_get ##### -->
+<para>
+Private function to get an argument and argument info from an object.
+</para>
+
+@object: the object whose argument should be retrieved.
+@arg: the argument, for the name on input, the rest is filled on output.
+@info: a #GtkArgInfo structure to optionally fill in.
+
+<!-- ##### FUNCTION gtk_object_arg_get_info ##### -->
+<para>
+Query information about an argument type.
+</para>
+
+@object_type: type of object to query about.
+@arg_name: name of the argument.
+@info_p: pointer to be filled in with a pointer to the GtkArgInfo.
+@Returns: an error message, or NULL on success.
+It is the caller's responsibility to call g_free() in the event of error.
+
+<!-- ##### FUNCTION gtk_object_arg_set ##### -->
+<para>
+Private function to set an argument and argument info to an object.
+</para>
+
+@object: the object whose argument should be set.
+@arg: the argument.
+@info: infomation about this type of argument in general.
+
+<!-- ##### FUNCTION gtk_object_args_collect ##### -->
+<para>
+Private: Gets an array of #GtkArgs from a va_list C structure.
+</para>
+
+@object_type: the type of object to collect arguments for.
+@arg_list_p: pointer to be filled in with a list of parsed arguments.
+@info_list_p: optional pointer for a returned list #GtkArgInfos.
+@first_arg_name: name of first argument.
+@var_args: value of first argument, followed by more key/value pairs,
+terminated by NULL.
+@Returns: an error message, or NULL on success.
+It is the caller's responsibility to call g_free() in the event of error.
+
+<!-- ##### FUNCTION gtk_object_class_add_signals ##### -->
+<para>
+Add an array of signals to a #GtkObjectClass.
+Usually this is called when registering a new type of object.
+</para>
+
+@klass: the object class to append signals to.
+@signals: the signals to append.
+@nsignals: the number of signals being appended.
+
+<!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->
+<para>
+Define a signal-handler for a new signal on an already defined
+object.
+</para>
+<para>
+See the signal documentation for more general information.
+</para>
+
+@klass: the object class to define the signal for.
+@name: the name of the signal.
+@signal_flags: the default emission behavior for the signal.
+See gtk_signal_new().
+@marshaller: a function that will take an array of GtkArgs
+and invoke the appropriate handler with the normal calling
+conventions.
+@return_val: specify the return-value type for the signal
+(or GTK_TYPE_NONE for no return-value).
+@nparams: specify the number of parameters the signal
+receives from the caller of gtk_signal_emit().
+@Varargs: list of nparams #GtkTypes to pass to the signal handlers.
+@Returns: the signal id. (See #GtkSignals)
+
+<!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->
+<para>
+Define a signal-handler for a new signal on an already defined
+object.
+</para>
+
+@klass: the object class to define the signal for.
+@name: the name of the signal.
+@signal_flags: the default emission behavior for the signal.
+See gtk_signal_new().
+@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array
+of arguments, and invokes the function using the appropriate
+calling conventions. Usually just select a function
+out of gtkmarshal.h.
+@return_val: specify the return-value type for the signal (possibly
+#GTK_TYPE_NONE).
+@nparams: specify the number of parameters the signal
+receives from the caller of gtk_signal_emit().
+@params: array of #GtkTypes the signal handlers for this signal
+should have in their prototype (of length nparams).
+@Returns: the signal id. (See #GtkSignals)
+
+<!-- ##### FUNCTION gtk_object_constructed ##### -->
+<para>
+Mark an allocated object as constructed.
+This is used for situations
+that require precise control of the construction process.
+</para>
+<para>
+This is done when gtk_object_default_construct() is inadequate.
+In #GtkCList the need arises because #GtkCList does construction work that
+must happen <emphasis>after</emphasis> its derivers. This work
+cannot be done in an initializer function, so an alternate
+constructor is mandatory. It calls gtk_object_constructed() to
+indicate it has done its job, so that no other constructor will
+be invoked.
+</para>
+<para>
+Normally this function is just automatically run from
+gtk_object_default_construct().
+</para>
+
+@object: object which has been constructed. This is usually
+done automatically by gtk_object_new() and gtk_object_newv().
+
+<!-- ##### FUNCTION gtk_object_default_construct ##### -->
+<para>
+This function is called to construct arguments that haven't been initialized
+but have the #GTK_ARG_CONSTRUCT flag set.
+</para>
+<para>
+All number arguments are set to 0. All pointers and strings
+are set to NULL.
+</para>
+<para>
+Normally invoked by gtk_object_new() automatically; gtk_type_new() can
+be used to bypass it.
+</para>
+
+@object: the object to initialize.
+
+<!-- ##### FUNCTION gtk_object_getv ##### -->
+<para>
+Gets an array of argument values from an object.
+</para>
+
+@object: the object to get arguments from.
+@n_args: the number of arguments to query.
+@args: the arguments to fill in.
+
+<!-- ##### FUNCTION gtk_object_newv ##### -->
+<para>
+Construct an object with an array of arguments.
+</para>
+
+@object_type: the type of the object to create.
+@n_args: the number of arguments to set.
+@args: an array of n_args arguments (which are name and value pairs).
+@Returns: the new GtkObject.
+
+<!-- ##### FUNCTION gtk_object_query_args ##### -->
+<para>
+Get all the arguments that may be used for a given type.
+</para>
+<para>
+In Java, this type of mechanism is called
+<wordasword>introspection</wordasword>. It is used by applications
+like Glade, that have to determine what can be done to an object
+at run-time.
+</para>
+
+@class_type: the GtkType of the ObjectClass
+(returned from GTK_OBJECT_CLASS(class)->type for example).
+@arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to
+each argument. You must g_free() this if you request it.
+@n_args: the number of arguments is returned in this field.
+@Returns: an array of arguments, that you must deallocate with g_free().
+
+<!-- ##### FUNCTION gtk_object_setv ##### -->
+<para>
+Set an array of arguments.
+</para>
+
+@object: the object whose arguments should be set.
+@n_args: the number of arguments to set.
+@args: the desired values, as an array of #GtkArgs (which contain
+the names, types, and values of the arguments).
+
+<!-- ##### FUNCTION gtk_paint_cross ##### -->
+<para>
+
+</para>
+
+@style:
+@window:
+@state_type:
+@shadow_type:
+@area:
+@widget:
+@detail:
+@x:
+@y:
+@width:
+@height:
+
+<!-- ##### FUNCTION gtk_paint_oval ##### -->
+<para>
+
+</para>
+
+@style:
+@window:
+@state_type:
+@shadow_type:
+@area:
+@widget:
+@detail:
+@x:
+@y:
+@width:
+@height:
<!-- ##### FUNCTION gtk_paint_ramp ##### -->
<para>
@width:
@height:
+<!-- ##### FUNCTION gtk_paned_compute_position ##### -->
+<para>
+Internal function used by #GtkHPaned and #GtkVPaned
+</para>
+
+@paned:
+@allocation:
+@child1_req:
+@child2_req:
+
+<!-- ##### FUNCTION gtk_rc_init ##### -->
+<para>
+Internal function.
+</para>
+
+
+<!-- ##### FUNCTION gtk_ruler_draw_pos ##### -->
+<para>
+
+</para>
+
+@ruler: the gtkruler
+
+<!-- ##### FUNCTION gtk_ruler_draw_ticks ##### -->
+<para>
+
+</para>
+
+@ruler: the gtkruler
+
+<!-- ##### FUNCTION gtk_signal_add_emission_hook_full ##### -->
+<para>
+Add an emission hook for a type of signal, for any object.
+(with control of what happens when the hook is
+destroyed).
+</para>
+
+@signal_id: the type of signal add the hook for.
+@hook_func: the function to invoke to handle the hook.
+@data: the user data passed in to hook_func.
+@destroy: a function to invoke when the hook is destroyed,
+to clean up any allocation done just for this
+signal handler.
+@Returns: the id (that you may pass as a parameter
+to gtk_signal_remove_emission_hook()).
+
+<!-- ##### FUNCTION gtk_signal_handler_pending_by_id ##### -->
+<para>
+Returns whether a connection id is valid (and optionally not blocked).
+</para>
+
+@object: the object to search for the desired handler.
+@handler_id: the connection id.
+@may_be_blocked: whether it is acceptable to return a blocked
+handler.
+@Returns: TRUE if the signal exists and wasn't blocked,
+unless #may_be_blocked was specified. FALSE otherwise.
+
+<!-- ##### FUNCTION gtk_signal_handlers_destroy ##### -->
+<para>
+Destroy all the signal handlers connected to an object.
+This is done automatically when the object is destroyed.
+</para>
+<para>
+This function is labeled private.
+</para>
+
+@object: the object whose signal handlers should be destroyed.
+
+<!-- ##### MACRO gtk_signal_init ##### -->
+<para>
+
+</para>
+
+
<!-- ##### FUNCTION gtk_signal_n_emissions ##### -->
<para>
Find out the recursion depth of emissions for a particular type
and decreases by one when #gtk_signal_emit() returns.
</para>
-@object: the object with the signal handler.
-@signal_id: the signal id.
-@Returns: the recursion depth of emissions of this signal for this
-object.
+@object: the object with the signal handler.
+@signal_id: the signal id.
+@Returns: the recursion depth of emissions of this signal for this
+object.
+
+<!-- ##### FUNCTION gtk_signal_n_emissions_by_name ##### -->
+<para>
+Find out the recursion depth of emissions for a particular type
+of signal and object. Just like gtk_signal_n_emissions()
+except it will lookup the signal id for you.
+</para>
+
+@object: the object with the signal handler.
+@name: the signal name.
+@Returns: the recursion depth of emissions of this signal for this
+object.
+
+<!-- ##### FUNCTION gtk_signal_query ##### -->
+<para>
+Obtain information about a signal.
+</para>
+
+@signal_id: the signal type identifier.
+@Returns: a pointer to a GtkSignalQuery structure
+which contains all the information, or NULL.
+The pointer is allocated just for you: you must g_free() it.
+
+<!-- ##### FUNCTION gtk_signal_set_funcs ##### -->
+<para>
+These set default functions to call when the user didn't
+supply a function when connecting. (These are rarely
+used, and probably only for language bindings)
+</para>
+<para>
+By default, there are no such functions.
+</para>
+
+@marshal_func: the function to invoke on every handlers for which there
+isn't a function pointer. May be NULL.
+@destroy_func: the function to invoke when each hook is destroyed.
+May be NULL.
+
+<!-- ##### FUNCTION gtk_text_buffer_copy ##### -->
+<para>
+
+</para>
+
+@buffer:
+@time:
+
+<!-- ##### FUNCTION gtk_text_buffer_cut ##### -->
+<para>
+
+</para>
+
+@buffer:
+@time:
+@interactive:
+@default_editable:
+
+<!-- ##### FUNCTION gtk_text_buffer_find_regexp ##### -->
+<para>
+
+</para>
+
+@buffer:
+@regexp:
+@start:
+@end:
+@Returns:
+
+<!-- ##### FUNCTION gtk_text_buffer_find_string ##### -->
+<para>
+
+</para>
+
+@buffer:
+@iter:
+@str:
+@start:
+@end:
+@Returns:
+
+<!-- ##### FUNCTION gtk_text_buffer_get_clipboard_contents ##### -->
+<para>
+
+</para>
+
+@buffer:
+@Returns:
+
+<!-- ##### FUNCTION gtk_text_buffer_get_tags ##### -->
+<para>
+
+</para>
+
+@buffer:
+@iter:
+@Returns:
+
+<!-- ##### FUNCTION gtk_text_buffer_insert_pixmap ##### -->
+<para>
+
+</para>
+
+@buffer:
+@iter:
+@pixmap:
+@mask:
+
+<!-- ##### FUNCTION gtk_text_buffer_paste_primary_selection ##### -->
+<para>
+
+</para>
+
+@buffer:
+@override_location:
+@time:
+@interactive:
+@default_editable:
+
+<!-- ##### FUNCTION gtk_text_buffer_set_clipboard_contents ##### -->
+<para>
+
+</para>
+
+@buffer:
+@text:
-<!-- ##### FUNCTION gtk_text_buffer_insert_pixmap ##### -->
+<!-- ##### FUNCTION gtk_text_buffer_spew ##### -->
<para>
</para>
@buffer:
-@iter:
-@pixmap:
-@mask:
-<!-- ##### ARG GtkTextTag:justify-set ##### -->
+<!-- ##### FUNCTION gtk_text_iter_forward_to_newline ##### -->
<para>
</para>
+@iter:
+@Returns:
-<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK_C_CALLBACK ##### -->
+<!-- ##### FUNCTION gtk_text_iter_get_pixmap ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@iter:
+@pixmap:
+@mask:
+@Returns:
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT_POINTER_INT_INT ##### -->
+<!-- ##### FUNCTION gtk_text_iter_in_region ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@iter:
+@start:
+@end:
+@Returns:
-<!-- ##### MACRO GTK_VALUE_ARGS ##### -->
+<!-- ##### FUNCTION gtk_text_iter_next_char ##### -->
<para>
-Use to get the value of a GtkArg whose GtkType is GTK_TYPE_ARGS
+
</para>
-@a:
+@iter:
+@Returns:
-<!-- ##### FUNCTION gtk_menu_factory_add_entries ##### -->
+<!-- ##### FUNCTION gtk_text_iter_prev_char ##### -->
<para>
</para>
-@factory:
-@entries:
-@nentries:
+@iter:
+@Returns:
-<!-- ##### SIGNAL GtkEditable::move-to-row ##### -->
+<!-- ##### FUNCTION gtk_text_mark_deleted ##### -->
<para>
-An action signal. Move the cursor to the given row.
+
</para>
-@editable: the object which received the signal.
-@row: the row to move to. (A negative value indicates
- the last row)
+@mark:
+@Returns:
-<!-- ##### FUNCTION gtk_signal_set_funcs ##### -->
+<!-- ##### FUNCTION gtk_text_mark_is_visible ##### -->
<para>
-These set default functions to call when the user didn't
-supply a function when connecting. (These are rarely
-used, and probably only for language bindings)
+
</para>
+
+@mark:
+@Returns:
+
+<!-- ##### FUNCTION gtk_text_mark_ref ##### -->
<para>
-By default, there are no such functions.
+
</para>
-@marshal_func: the function to invoke on every handlers for which there
-isn't a function pointer. May be NULL.
-@destroy_func: the function to invoke when each hook is destroyed.
-May be NULL.
+@mark:
+@Returns:
-<!-- ##### FUNCTION gtk_im_context_simple_new ##### -->
+<!-- ##### FUNCTION gtk_text_mark_unref ##### -->
<para>
</para>
-@Returns:
+@mark:
-<!-- ##### FUNCTION gtk_paint_cross ##### -->
+<!-- ##### FUNCTION gtk_text_view_get_iter_at_pixel ##### -->
<para>
</para>
-@style:
-@window:
-@state_type:
-@shadow_type:
-@area:
-@widget:
-@detail:
+@text_view:
+@iter:
@x:
@y:
-@width:
-@height:
-<!-- ##### ARG GtkObject:signal ##### -->
+<!-- ##### FUNCTION gtk_theme_engine_create_rc_style ##### -->
<para>
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects
-the signal to the object.
+
</para>
+@engine:
+@Returns:
-<!-- ##### FUNCTION gtk_type_describe_heritage ##### -->
+<!-- ##### FUNCTION gtk_theme_engine_get ##### -->
<para>
-Print the types @type inherits from.
+
</para>
-@type: GtkType
+@name:
+@Returns:
-<!-- ##### FUNCTION gtk_text_buffer_set_clipboard_contents ##### -->
+<!-- ##### FUNCTION gtk_theme_engine_ref ##### -->
<para>
</para>
-@buffer:
-@text:
+@engine:
-<!-- ##### ENUM GtkFontFilterType ##### -->
+<!-- ##### FUNCTION gtk_theme_engine_register_type ##### -->
<para>
-A set of bit flags used to specify the filter being set
-when calling gtk_font_selection_dialog_set_filter() or
-gtk_font_selection_set_filter().
+
</para>
-@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
-@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the
-'Filter' page of the #GtkFontSelection widget.
+@engine:
+@parent_type:
+@type_name:
+@type_info:
+@Returns:
-<!-- ##### SIGNAL GtkEditable::move-cursor ##### -->
+<!-- ##### FUNCTION gtk_theme_engine_unref ##### -->
<para>
-An action signal. Move the cursor position.
+
</para>
-@editable: the object which received the signal.
-@x: horizontal distance to move the cursor.
-@y: vertical distance to move the cursor.
+@engine:
-<!-- ##### FUNCTION gtk_type_parent_class ##### -->
+<!-- ##### FUNCTION gtk_themes_exit ##### -->
<para>
-Return the class of the parent. Initialize the class if necessary.
-Return NULL if anything goes wrong.
+
</para>
-@type: GtkType
-@Returns: gpointer to the klass.
+@error_code:
-<!-- ##### USER_FUNCTION GtkSignalDestroy ##### -->
+<!-- ##### FUNCTION gtk_themes_init ##### -->
<para>
-A function which you can use to clean up when the
-signal handler is destroyed.
+
</para>
+
+@argc:
+@argv:
+
+<!-- ##### FUNCTION gtk_trace_referencing ##### -->
<para>
-For example, if your handler requires a few variables
-that you made into a struct and allocated (using g_new()
-or something), then you will probably want to free
-it as soon as the hook is destroyed. This will
-allow you to do that. (For this in particular
-it is convenient to pass g_free() as a #GtkSignalDestroy
-function).
+Private: print debugging information while doing a gtk_object_ref() or
+a gtk_object_unref().
</para>
-@data: The user data associated with the hook that is being
-destroyed.
+@object: object to reference or unreference.
+@func: name of caller's function to print (used within macros).
+@dummy: unused.
+@line: line number (used within macros).
+@do_ref: whether to reference or unreference.
-<!-- ##### FUNCTION gtk_window_set_default ##### -->
+<!-- ##### FUNCTION gtk_tree_model_sort_resort ##### -->
<para>
</para>
-@window:
-@defaultw:
+@tree_model_sort:
-<!-- ##### FUNCTION gtk_tree_store_setv ##### -->
+<!-- ##### FUNCTION gtk_tree_model_sort_set_sort_col ##### -->
<para>
</para>
-@tree_store:
-@iter:
-@var_args:
+@tree_model_sort:
+@sort_col:
-<!-- ##### SIGNAL GtkTextBuffer::delete-text ##### -->
+<!-- ##### FUNCTION gtk_tree_selection_new ##### -->
<para>
</para>
-@textbuffer: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
+@Returns:
<!-- ##### FUNCTION gtk_tree_selection_new_with_tree_view ##### -->
<para>
@tree_view:
@Returns:
-<!-- ##### FUNCTION gtk_marshal_NONE__INT ##### -->
+<!-- ##### FUNCTION gtk_tree_selection_set_tree_view ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@selection:
+@tree_view:
-<!-- ##### ARG GtkObject:object-signal ##### -->
+<!-- ##### FUNCTION gtk_tree_selection_set_type ##### -->
<para>
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects
-the signal to the object, so that the user data and objects
-and swapped when the signal handler is invoked.
+
</para>
+
+@selection:
+@type:
+
+<!-- ##### FUNCTION gtk_tree_store_get_root_iter ##### -->
<para>
-This is useful for handlers that are primarily notifying
-other objects and could just invoke an already existing function
-if the parameters were swapped.
-See gtk_signal_connect_object() for more details.
+
</para>
+@tree_store:
+@iter:
-<!-- ##### FUNCTION gtk_draw_ramp ##### -->
+<!-- ##### FUNCTION gtk_tree_store_getv ##### -->
<para>
</para>
-@style:
-@window:
-@state_type:
-@shadow_type:
-@arrow_type:
-@x:
-@y:
-@width:
-@height:
+@tree_store:
+@iter:
+@var_args:
-<!-- ##### MACRO GTK_WIDGET_LEAVE_PENDING ##### -->
+<!-- ##### FUNCTION gtk_tree_store_new_with_values ##### -->
<para>
</para>
-@obj:
+@n_columns:
+@Varargs:
+@Returns:
+
+<!-- ##### FUNCTION gtk_tree_store_setv ##### -->
+<para>
+
+</para>
+
+@tree_store:
+@iter:
+@var_args:
+
+<!-- ##### FUNCTION gtk_tree_view_column_get_col_type ##### -->
+<para>
+
+</para>
+
+@tree_column:
+@Returns:
-<!-- ##### MACRO gtk_marshal_NONE__UINT ##### -->
+<!-- ##### FUNCTION gtk_tree_view_column_get_justification ##### -->
<para>
</para>
+@tree_column:
+@Returns:
-<!-- ##### MACRO GTK_WIDGET_IN_REPARENT ##### -->
+<!-- ##### FUNCTION gtk_tree_view_column_get_size ##### -->
<para>
</para>
-@obj:
+@tree_column:
+@Returns:
-<!-- ##### FUNCTION gtk_accel_group_marshal_add ##### -->
+<!-- ##### FUNCTION gtk_tree_view_column_get_title ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@tree_column:
+@Returns:
<!-- ##### FUNCTION gtk_tree_view_column_set_col_type ##### -->
<para>
@tree_column:
@type:
-<!-- ##### ARG GtkTextTag:overstrike-set ##### -->
+<!-- ##### FUNCTION gtk_tree_view_column_set_header_active ##### -->
<para>
</para>
+@tree_column:
+@active:
-<!-- ##### FUNCTION gtk_marshal_INT__POINTER_CHAR_CHAR ##### -->
+<!-- ##### FUNCTION gtk_tree_view_column_set_header_clickable ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@tree_column:
+@active:
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT ##### -->
+<!-- ##### FUNCTION gtk_tree_view_column_set_justification ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@tree_column:
+@justification:
-<!-- ##### FUNCTION gtk_accel_group_marshal_remove ##### -->
+<!-- ##### FUNCTION gtk_tree_view_column_set_size ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
-@args:
+@tree_column:
+@size:
+@width:
-<!-- ##### SIGNAL GtkWidget::draw ##### -->
+<!-- ##### FUNCTION gtk_tree_view_move_to ##### -->
<para>
</para>
-@widget: the object which received the signal.
-@area:
+@tree_view:
+@path:
+@column:
+@row_align:
+@col_align:
-<!-- ##### MACRO gtk_marshal_NONE__STRING_INT_POINTER ##### -->
+<!-- ##### FUNCTION gtk_tree_view_set_headers_active ##### -->
<para>
</para>
+@tree_view:
+@active:
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER ##### -->
+<!-- ##### FUNCTION gtk_type_check_class_cast ##### -->
<para>
-
+Given a GtkTypeClass pointer @klass, and a GtkType @cast_type, make
+sure that it's okay to cast something of that @klass into a @cast_type.
</para>
-@object:
-@func:
-@func_data:
-@args:
+@klass: GtkTypeClass*
+@cast_type: GtkType
+@Returns: Always return @klass.
-<!-- ##### FUNCTION gtk_rc_init ##### -->
+<!-- ##### FUNCTION gtk_type_check_object_cast ##### -->
<para>
-Internal function.
+Given a pointer to a GtkTypeObject @type_object, and a GtkType @cast_type,
+make sure that it's okay to cast @type_object into a @cast_type.
</para>
+@type_object: GtkTypeObject*
+@cast_type: GtkType
+@Returns: the same GtkTypeObject* as @type_object
-<!-- ##### FUNCTION gtk_signal_query ##### -->
+<!-- ##### FUNCTION gtk_type_children_types ##### -->
<para>
-Obtain information about a signal.
+Return the pointer to the type's children's types.
</para>
-@signal_id: the signal type identifier.
-@Returns: a pointer to a GtkSignalQuery structure
-which contains all the information, or NULL.
-The pointer is allocated just for you: you must g_free() it.
+@type: GtkType
+@Returns: pointer to a GList
-<!-- ##### FUNCTION gtk_signal_n_emissions_by_name ##### -->
+<!-- ##### FUNCTION gtk_type_describe_heritage ##### -->
<para>
-Find out the recursion depth of emissions for a particular type
-of signal and object. Just like gtk_signal_n_emissions()
-except it will lookup the signal id for you.
+Print the types @type inherits from.
</para>
-@object: the object with the signal handler.
-@name: the signal name.
-@Returns: the recursion depth of emissions of this signal for this
-object.
+@type: GtkType
-<!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:See_Also ##### -->
+<!-- ##### FUNCTION gtk_type_describe_tree ##### -->
<para>
-
+Given a @type, describe all of its children, and their children. Only
+show the size if @show_size is true.
</para>
+@type: GtkType
+@show_size: gboolean
-<!-- ##### SIGNAL GtkTextView::delete ##### -->
+<!-- ##### FUNCTION gtk_type_free ##### -->
<para>
-
+Given the type of an object and a pointer to it, the object is freed.
</para>
-@textview: the object which received the signal.
-@arg1:
-@arg2:
+@type: GtkType
+@mem: gpointer to the object
-<!-- ##### MACRO gtk_marshal_ENUM__ENUM ##### -->
+<!-- ##### FUNCTION gtk_type_get_varargs_type ##### -->
<para>
+Get the varargs type associated with @foreign_type
+</para>
+@foreign_type: GtkType
+@Returns: GtkType
+
+<!-- ##### FUNCTION gtk_type_parent_class ##### -->
+<para>
+Return the class of the parent. Initialize the class if necessary.
+Return NULL if anything goes wrong.
</para>
+@type: GtkType
+@Returns: gpointer to the klass.
-<!-- ##### MACRO gtk_widget_push_visual ##### -->
+<!-- ##### FUNCTION gtk_type_query ##### -->
<para>
+Given a type, return various interesting parameters of the type.
+</para>
+
+@type: GtkType
+@Returns: GtkTypeQuery*
+<!-- ##### FUNCTION gtk_type_register_enum ##### -->
+<para>
+Register a new set of enum @values and give them the name in
+@type_name.
</para>
-@v:
-@visual:
+@type_name: must not be null.
+@values: GtkEnumValue*
+@Returns:
-<!-- ##### FUNCTION gtk_container_register_toplevel ##### -->
+<!-- ##### FUNCTION gtk_type_register_flags ##### -->
<para>
+Register a new set of flags @values and give them the name in
+@type_name.
+</para>
+
+@type_name: must not be null.
+@values: GtkFlagValue*
+@Returns:
+<!-- ##### FUNCTION gtk_type_set_chunk_alloc ##### -->
+<para>
+Set the mem_chunk size so it will hold @n_chunks of the objects of that @type.
</para>
-@container:
+@type: There must be an unlocked TypeNode associated with this type otherwise nothing happens.
+@n_chunks:
-<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:Title ##### -->
-GtkIMContextSimple
+<!-- ##### FUNCTION gtk_type_set_varargs_type ##### -->
+<para>
+Set the varargs type for a fundamental type @foreign_type.
+</para>
+@foreign_type: Must be a GtkType with a sequence number of zero. Must not be a
+fundamental type.
+@varargs_type: Must be a GtkType which is either structured or flag, or NONE.
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_INT_INT_POINTER_UINT_UINT ##### -->
+<!-- ##### FUNCTION gtk_widget_get ##### -->
<para>
</para>
+@widget:
+@arg:
-<!-- ##### MACRO GTK_VALUE_C_CALLBACK ##### -->
+<!-- ##### FUNCTION gtk_widget_getv ##### -->
<para>
-Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK
+
</para>
-@a:
+@widget:
+@nargs:
+@args:
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_INT_INT ##### -->
+<!-- ##### FUNCTION gtk_widget_newv ##### -->
<para>
</para>
-@object:
-@func:
-@func_data:
+@type:
+@nargs:
@args:
+@Returns:
-<!-- ##### SIGNAL GtkTextView::move-insert ##### -->
+<!-- ##### MACRO gtk_widget_pop_visual ##### -->
<para>
</para>
-@textview: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
+@v:
-<!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:Long_Description ##### -->
+<!-- ##### MACRO gtk_widget_push_visual ##### -->
<para>
</para>
+@v:
+@visual:
-<!-- ##### FUNCTION gtk_tree_view_set_headers_active ##### -->
+<!-- ##### FUNCTION gtk_widget_render_stock_icon ##### -->
<para>
</para>
-@tree_view:
-@active:
+@widget:
+@stock_id:
+@size:
+@detail:
+@Returns:
-<!-- ##### FUNCTION gtk_text_buffer_find_regexp ##### -->
+<!-- ##### MACRO gtk_widget_set_default_visual ##### -->
<para>
</para>
-@buffer:
-@regexp:
-@start:
-@end:
-@Returns:
+@v:
+@visual:
-<!-- ##### FUNCTION gtk_menu_factory_add_subfactory ##### -->
+<!-- ##### MACRO gtk_widget_set_visual ##### -->
<para>
</para>
-@factory:
-@subfactory:
-@path:
+@w:
+@v:
+@widget:
+@visual:
-<!-- ##### ENUM GtkTextViewScrollType ##### -->
+<!-- ##### FUNCTION gtk_widget_setv ##### -->
<para>
</para>
-@GTK_TEXT_SCROLL_TO_TOP:
-@GTK_TEXT_SCROLL_TO_BOTTOM:
-@GTK_TEXT_SCROLL_PAGE_DOWN:
-@GTK_TEXT_SCROLL_PAGE_UP:
+@widget:
+@nargs:
+@args:
-<!-- ##### FUNCTION gtk_text_iter_next_char ##### -->
+<!-- ##### FUNCTION gtk_window_add_embedded_xid ##### -->
<para>
</para>
-@iter:
-@Returns:
+@window:
+@xid:
-<!-- ##### FUNCTION gtk_tree_store_get_root_iter ##### -->
+<!-- ##### FUNCTION gtk_window_remove_embedded_xid ##### -->
<para>
</para>
-@tree_store:
-@iter:
+@window:
+@xid:
-<!-- ##### STRUCT GtkTextBTree ##### -->
+<!-- ##### FUNCTION gtk_window_set_default ##### -->
+<para>
+
+</para>
+
+@window:
+@defaultw:
+
+<!-- ##### FUNCTION gtk_window_set_focus ##### -->
<para>
</para>
+@window:
+@focus:
@tree_view:
@button:
@child:
+@arrow:
+@alignment:
@window:
-@justification:
+@xalign:
@id:
@width:
@min_width:
@cell:
@attributes:
@column_type:
+@sort_order:
@visible:
@button_active:
@dirty:
+@show_sort_indicator:
<!-- ##### ENUM GtkTreeViewColumnSizing ##### -->
<para>
@title:
-<!-- ##### FUNCTION gtk_tree_view_column_get_title ##### -->
-<para>
-
-</para>
-
-@tree_column:
-@Returns:
-
-
<!-- ##### FUNCTION gtk_tree_view_column_set_clickable ##### -->
<para>
@Returns:
-<!-- ##### FUNCTION gtk_tree_view_column_set_justification ##### -->
-<para>
-
-</para>
-
-@tree_column:
-@justification:
-
-
-<!-- ##### FUNCTION gtk_tree_view_column_get_justification ##### -->
-<para>
-
-</para>
-
-@tree_column:
-@Returns:
-
-
<!-- ##### FUNCTION gtk_tree_view_column_clicked ##### -->
<para>
projects / gtk4.git / commitdiff